Amiga ISO Collection/AmigaUtilCD1.iso/FileMover/HF-OM1.DMS/in.adf/OpusSDK.lha/SDK/docs/hooks.doc

Text File | 1997-05-09 | 20.5 KB | 519 lines

The DOpus Hooks are a series of hook functions which offer you direct
access to some of the internals of Directory Opus. Using these functions
offers significant speed advantages and is considerably more convenient
than using ARexx.

To get a pointer to the hooks, you need to initialise a DOpusCallbackInfo
structure and send it to the Opus main process. Set the dc_Count field to
the number of hooks you want (the best thing is to set it to DOPUS_HOOK_COUNT).

    DOpusCallbackInfo info;
    short num;

    info.dc_Count=DOPUS_HOOK_COUNT;
    num=IPC_Command(opus_main_ipc,HOOKCMD_GET_CALLBACKS,0,&info,0,REPLY_NO_PORT);

The return value from this message will be the number of hooks copied into your
structure. If this is 0, you will know this is an older version of Opus that does
not support hooks (this is a cheap way to do a version check).

More hook functions will be added in the future, and this structure will grow
appropriately. You should never attempt to use a hook without checking to see
if its pointer is valid.

Once you have an initialised structure you can call the hook functions
directly (ie no message passing).



    APTR dc_CreateFileEntry(   ULONG lister,
                               struct FileInfoBlock *fib,
                               BPTR lock);

    This function creates a file entry, ready to be added to a lister. Pass it
    the lister handle and a filled out FileInfoBlock structure. The 'lock'
    argument is optional; if not set to NULL it should be a lock on the
    directory containing the FileInfoBlock (and is used for resolving links).
    The information in the FileInfoBlock structure is copied and can be
    disposed of when this function returns. The FileInfoBlock structure does
    not need to be longword-aligned.


    void dc_FileSet(   ULONG lister,
                       APTR entry,
                       struct TagItem *tags);

    This command allows you to add or modify entry information. It is mainly
    used BEFORE an entry has been added to a list but can be used after. Pass
    an array of tags with the item ID in ti_Tag and the new value in ti_Data.
    Valid tags for this function are:

        HFFS_NAME       - The name of the entry (char *)
        HFFS_SIZE       - The size of the entry (ULONG)
        HFFS_PROTECTION - Protection flags      (ULONG)
        HFFS_DATE       - Entry date            (struct Datestamp *)
        HFFS_COMMENT    - Comment               (char *)
        HFFS_SELECTED   - Selected state        (BOOL)
        HFFS_LINK       - Indicates a 'link'    (BOOL)
        HFFS_COLOUR     - Entry colour          (1 = device colour,
                                                 2 = assign colour)
        HFFS_USERDATA   - User-defined data     (ULONG)
        HFFS_FILETYPE   - Filetype description  (char *)
        HFFS_DISPLAY    - Custom display string (char *)
        HFFS_VERSION    - Version Information   (VersionInfo *)
        HFFS_MENU       - Custom menus          (struct List *)

    A note about custom menus: To add custom menus to the pop-up menu for an
    entry, use the HFFS_MENU tag. ti_Data should point to a struct List *, the
    ln_Name field of the nodes should contain the names of the menu items.
    Note that the names of menu items are NOT copied (to conserve memory) and
    so must remain valid while the entry is in use.


    void dc_SortFileList(   ULONG lister,
                            struct List *list,
                            long file_count,
                            long dir_count);

    This function allows you to add and quicksort a list of entries at once.
    It is much faster than multiple dc_AddFileEntry() commands. To use it, you
    should add the return values from your calls to dc_CreateFileEntry() to an
    initialised exec List structure. Then, pass the list structure along with a
    count of the number of files and number of directories in the list to this
    function. Eg,

        struct List file_list;
        long file_count=0,dir_count=0;
        DOpusCallbackInfo info;

        NewList(&file_list);

        while (entries_to_add)
        {
            entry=info.dc_CreateFileEntry(lister,fib,0);
            AddTail(&file_list,(struct Node *)entry);

            if (fib->fib_DirEntryType<0) ++file_count;
            else ++dir_count;
        }

        info.dc_SortFileList(lister,&list,file_count,dir_count);



    APTR dc_AddFileEntry(    ULONG lister,
                             APTR entry,
                             BOOL sort);

    This function adds a file entry to a lister. Pass it the lister handle
    and the return value of the dc_CreateFileEntry() command. If sort==TRUE,
    the entry will be added using the lister's current sort method, otherwise
    it will just be added to the end of the list. If you have a whole directory
    to add, dc_SortFileList() is quicker. However, using dc_AddFileEntry() with
    sort==FALSE and then calling dc_ResortLister() isn't that much slower.


    void dc_ResortLister(    ULONG lister,
                             ListFormat *format);

    This hook allows you to resort the lister, optionally with a new sort
    format. If you pass NULL for the format parameter, the list will be
    resorted using the current settings. Use this hook if you have added
    multiple files with the dc_AddFileEntry() hook and now wish to sort them
    (a quicksort will be used).


    void dc_RefreshLister(    ULONG lister,
                             ULONG flags);

    Allows you to refresh a lister; you should call it after adding entries
    with the above commands. The HOOKREFRESH_DATE flag indicates that the
    lister should update its datestamp (to prevent it being automatically
    re-read). The HOOKREFRESH_FULL flag causes a total refresh of the lister,
    including the title.


    void dc_LockFileList(    ULONG lister,
                             BOOL exclusive)

    You should use this to protect the file list from changes by other tasks.
    Set 'exclusive' to TRUE if you are going to be adding or removing entries
    from the list; set to FALSE if you are just looking at list entries.


    void dc_UnlockFileList(   ULONG lister)

    If you have locked the list with dc_LockFileList() you MUST call this
    function when you have finished.


    APTR dc_FindFileEntry(   ULONG lister,
                             char *name)

    Searches the file list for a named entry, and returns a handle to it if
    found. This handle can then be used with dc_FileSet() and dc_FileQuery(),
    or dc_RemoveFileEntry().


    void dc_RemoveFileEntry(   ULONG lister,
                               APTR entry)

    Removed an entry from a list and frees the memory associated with it. The
    lister display is not updated automatically.


    BOOL dc_FileQuery(   ULONG lister,
                         APTR entry,
                         struct TagItem *tags)

    Lets you query a file entry. This function uses the same tags as the
    dc_FileSet() function does. The ti_Data field of each TagItem should point
    to the appropriate memory area to store the result. That is,

        HFFS_NAME
        HFFS_COMMENT
        HFFS_FILETYPE
        HFFS_DIPSLAY

            For the string items, ti_Data MUST point to a buffer big enough to
            receive the string (256 characters is safe in most cases).

        HFFS_SIZE
        HFFS_PROTECTION
        HFFS_SELECTED
        HFFS_LINK
        HFFS_USERDATA

            For these items, ti_Data must point to a ULONG, in which the value
            will be stored.

        HFFS_DATE

            ti_Data must point to a (struct DateStamp), which will be used to
            store the date.

        HFFS_VERSION

            This tag is slightly different. ti_Data must point to a
            VersionInfo * (ie a 4-byte pointer, NOT an instance of a
            VersionInfo structure itself). DOpus will allocate a VersionInfo
            structure and store a pointer to it in the address you provide in
            ti_Data. When you have finished with the version information, you
            must call FreeVec() on the memory.


    void dc_ShowHelp(    char *file_name,
                         char *node_name)

    Calls the internal Opus help system to display help (via AmigaGuide) on the
    given topic. If file_name is specified, it must be the name of an AmigaGuide
    help file in the dopus5:Help/ directory. If NULL is given for the file name,
    the default Opus help file will be used. node_name is the name within the
    guide of the node to display.


    *** The following hooks are a new interface to the old module callback
        system, and take and return similar parameters. The 'handle' parameter
        in any functions that take it is passed to the Module_Entry() function
        in your module ***

    APTR dc_ConvertEntry(    APTR entry)

    Takes an entry as returned by the dc_GetEntry() function and converts it to
    an entry you can use with the dc_FileSet()/dc_FileQuery()/etc.. functions.
    You MUST use this as the two entry types are not compatible with each other.
    Use the return value from this as the entry pointer to pass (the old entry
    pointer is still valid too).


    ULONG dc_GetLister(   APTR path)

    Takes a path as returned by the dc_GetSource(), etc functions, and converts
    it to a lister handle that you can use with the dc_AddFileEntry() and similar
    functions.


    APTR dc_GetSource(    APTR handle,
                          char *path)

    Copies the current source path into the supplied buffer (must be at least
    512 bytes in size). The return value is a pointer to the path handle; you
    can use this with other hook functions.
    This hook is the same as the old EXTCMD_GET_SOURCE callback function.


    APTR dc_EndSource(    APTR handle,
                          long ununsed)

    Call this hook if you are aborting early and do not wish to process
    further source paths. Set the 'unused' parameter to 0.
    This hook is the same as the old EXTCMD_END_SOURCE callback function.


    APTR dc_NextSource(    APTR handle,
                           char *path)

    Call this hook when you have finished with the first source path and want
    to move onto the next one. The return value is the new path handle, or
    NULL if there are no more source paths.
    This hook is the same as the old EXTCMD_NEXT_SOURCE callback function.


    void dc_UnlockSource(    APTR handle)

    When your module command is called, any source listers are locked
    automatically. Call this command when you want to unlock them (they
    are unlocked automatically when your module returns).
    This hook is the same as the old EXTCMD_UNLOCK_SOURCE callback function.


    void dc_GetDest(    APTR handle,
                        char *path)

    Copies the current destination path into the supplied buffer (must be at least
    512 bytes in size). The return value is a pointer to the path handle; you
    can use this with other hook functions. Call this command repeatedly to move
    through the destination paths. When all the destination paths have been used,
    this command will return NULL. If you call this command again, it will start
    again with the first destination path.
    This hook is the same as the old EXTCMD_GET_DEST callback function.


    void dc_EndDest(    APTR handle,
                        long continue)

    You must call this command when you have finished with one destination path,
    prior to calling dc_GetDest().
    This hook is the same as the old EXTCMD_END_DEST callback function.


    APTR dc_GetEntry(    APTR handle)

    This returns a pointer to the next entry in the current source path. Use
    the dc_ExamineEntry() hook function to get information about the entry.
    This hook is the same as the old EXTCMD_GET_ENTRY callback function.


    ULONG dc_ExamineEntry(    APTR entry,
                              long type)

    Returns information about an entry handle retrieved with dc_GetEntry().
    'type' can be either EE_NAME, which returns a pointer to the name,
    or EE_TYPE, which returns the type of the entry.


    void dc_EndEntry(    APTR handle,
                         APTR entry,
                         BOOL deselect)

    Call this hook when you have finished working with one entry and want
    to move on to the next. 'entry' is the pointer that was returned by
    dc_GetEntry(). Set 'deselect' to TRUE to have the entry deselected
    in the lister.
    This hook is the same as the old EXTCMD_NEXT_ENTRY callback function.


    void dc_ReloadEntry(    APTR handle,
                            APTR entry)

    This function marks the specified entry to be reloaded. When the
    function finishes, the entry will be reloaded to update any changes
    that your module might have made to it.
    This hook is the same as the old EXTCMD_RELOAD_ENTRY callback function.


    void dc_RemoveEntry(    APTR entry)

    This function marks the specified entry to be removed. When the
    function finishes, the entry will be removed from the lister it is
    in.
    This hook is the same as the old EXTCMD_REMOVE_ENTRY callback function.


    long dc_EntryCount(    APTR handle)

    Returns the number of selected entries for the function.
    This hook is the same as the old EXTCMD_ENTRY_COUNT callback function.


    long dc_AddFile(    APTR handle,
                        char *path,
                        struct FileInfoBlock *fib,
                        APTR lister)

    Allows you to add a file or directory to a lister. The 'path' field
    points to the full path of the file to add. 'fib' is an initialised
    FileInfoBlock which is used to create the file entry. The 'lister'
    pointer is obtained via a call to the dc_GetLister() function.
    The display is not updated until you call dc_DoChanges(), or your
    function returns.
    This hook is the same as the old EXTCMD_ADD_FILE callback function.


    void dc_DelFile(    APTR handle,
                        char *path,
                        char *name,
                        APTR lister)

    This removes the specified file from any listers it is currently
    shown in. The file itself is not deleted, only the display of it in
    the lister. The display is not updated until you call dc_DoChanges(),
    or your function returns.
    This hook is the same as the old EXTCMD_DEL_FILE callback function.


    void dc_LoadFile(    APTR handle,
                         char *path,
                         char *name,
                         long flags,
                         BOOL reload)

    This function is similar to dc_AddFile() except that it takes a
    filename and path and supplies the FileInfoBlock structure itself.
    'path' is the full path of the file and 'name' is the file name. If
    'flags' is set to LFF_ICON, the icon of the supplied file will be
    loaded instead of the file itself. If 'reload' is set to TRUE, an
    existing file will be reloaded (ie the old entry in the lister
    will be removed).
    This hook is the same as the old EXTCMD_LOAD_FILE callback function.


    void dc_DoChanges(    APTR handle)

    This command causes any changes made to listers by the dc_AddFile(),
    dc_DelFile() and dc_LoadFile() commands to be displayed. If your
    function returns without calling this command, the changes are
    displayed automatically.
    This hook is the same as the old EXTCMD_DO_CHANGES callback function.


    BOOL dc_CheckAbort(    APTR handle)

    This hook returns TRUE if your function has been aborted by the user.
    This could have occurred because the user pressed escape or clicked the
    close button on a lister, clicked the Abort button in the progress
    window or quit the program.
    This hook is the same as the old EXTCMD_CHECK_ABORT callback function.


    struct Window *dc_GetWindow(    APTR path)

    This function returns a pointer to the Window for the lister specified
    by the supplied path handle (as returned by dc_GetSource(), etc). This
    is useful if you want to open a requester over a lister window.
    This hook is the same as the old EXTCMD_GET_WINDOW callback function.


    struct MsgPort *dc_GetPort(    char *name)

    This function copies the name of the Opus ARexx port into the supplied
    buffer (max 40 bytes), and returns a pointer to the message port.
    This hook is the same as the old EXTCMD_GET_PORT callback function.


    struct Screen *dc_GetScreen(    char *name)

    This function copies the name of the Opus public screen into the
    supplied buffer (max 40 bytes), and returns a pointer to the screen.
    This hook is the same as the old EXTCMD_GET_SCREEN callback function.


    long dc_ReplaceReq(    struct Window *window,
                           struct Screen *screen,
                           IPCData *ipc,
                           struct FileInfoBlock *file1,
                           struct FileInfoBlock *file2,
                           long flags)

    This function shows a 'file exists - replace?' requester, comparing
    the two supplied files. Set either the value of 'window' or 'screen'
    to specify where the requester is to open. 'ipc' is your IPC pointer.
    'file1' and 'file2' are the two files. 'flags' should be set to 0
    for now.

    The result of this function is REPLACE_ABORT for abort, REPLACE_LEAVE
    for skip or REPLACE_REPLACE for replace. If the REPLACEF_ALL flag is
    set in the result, it indicates an 'All' gagdet (ie Skip All, Replace
    All).

    This hook is the same as the old EXTCMD_REPLACE_REQ callback function.


    DOpusScreenData *dc_GetScreenData(void)

    Returns a structure with useful information about the Opus screen. This
    structure is READ_ONLY! You must call dc_FreeScreenData() to free the
    structure when you have finished with it.
    This hook is the same as the old EXTCMD_GET_SCREENDATA callback function.


    void dc_FreeScreenData(    DOpusScreenData *data)

    Frees the result of a dc_GetScreenData() function call.
    This hook is the same as the old EXTCMD_FREE_SCREENDATA callback function.


    void dc_OpenProgress(    APTR path,
                             char *operation,
                             long total)

    This opens the lister progress indicator for the specified path handle.
    'operation' is the operation string displayed in the title bar, and
    'total' is the total number of files to process.
    This hook is the same as the old EXTCMD_OPEN_PROGRESS callback function.


    void dc_UpdateProgress(    APTR path,
                               char *name,
                               long count)

    This updates an open progress indicator. 'path' is the path handle that
    you previously opened a progress indicator for. 'name' is the new
    filename to display, and 'count' is the new count of files processed.
    This hook is the same as the old EXTCMD_UPDATE_PROGRESS callback function.


    void dc_CloseProgress(    APTR path)

    Closes the progress indicator for the specified path.
    This hook is the same as the old EXTCMD_CLOSE_PROGRESS callback function.


    long dc_SendCommand(    APTR handle,
                            char *command,
                            char **result,
                            ULONG flags)

    This command sends an ARexx instruction directly to the Opus ARexx port.
    If you want a result string returned, pass a pointer to a char * in
    'result', and set 'flags' to COMMANDF_RESULT. If a string is returned,
    your supplied pointer will have the address of the string stored in it.
    You MUST call FreeVec() on this pointer when you have finished with the
    result. This function returns the RC result of the call.
    This hook is the same as the old EXTCMD_SEND_COMMAND callback function.


    void dc_CheckDesktop(   char *path)

    This command is used when your program has just copied one or more files
    to a directory. You pass it the destination path that you copied the
    files to, and DOpus compares this path with the location of the Desktop
    folder. If they are the same, DOpus will then scan the Desktop folder and
    update the icons on-screen if necessary.
    This slightly clumsy method has been used because of problems in the
    system notification routines.


    short dc_GetDesktop(    char *buffer);

    This command lets you get the path of the DOpus Desktop Folder. The
    buffer you supply MUST be at least 256 bytes. The current Desktop Folder
    path will be copied to this buffer. The return value of this hook
    indicates the user's desktop settings:

                    0    desktop popup disabled
                    1    no default action
                    2    default : create leftout
                    3    default : move
                    4    default : copy