@database "amigaguide..hyper"
@master "Work:AmigaGuide/amigaguide.adoc"

@Node Main "amigaguide.adoc"
    @{" AddAmigaGuideHost() " Link "AddAmigaGuideHost()"}
    @{" AmigaGuideSignal() " Link "AmigaGuideSignal()"}
    @{" CloseAmigaGuide() " Link "CloseAmigaGuide()"}
    @{" ExpungeDataBases() " Link "ExpungeDataBases()"}
    @{" ExpungeXRef() " Link "ExpungeXRef()"}
    @{" GetAmigaGuideMsg() " Link "GetAmigaGuideMsg()"}
    @{" LoadXRef() " Link "LoadXRef()"}
    @{" LockAmigaGuideBase() " Link "LockAmigaGuideBase()"}
    @{" LockE() " Link "LockE()"}
    @{" OpenAmigaGuide() " Link "OpenAmigaGuide()"}
    @{" OpenAmigaGuideAsync() " Link "OpenAmigaGuideAsync()"}
    @{" OpenE() " Link "OpenE()"}
    @{" RemoveAmigaGuideHost() " Link "RemoveAmigaGuideHost()"}
    @{" ReplyAmigaGuideMsg() " Link "ReplyAmigaGuideMsg()"}
    @{" SendAmigaGuideCmd() " Link "SendAmigaGuideCmd()"}
    @{" SendAmigaGuideContext() " Link "SendAmigaGuideContext()"}
    @{" SetAmigaGuideContext() " Link "SetAmigaGuideContext()"}
    @{" UnlockAmigaGuideBase() " Link "UnlockAmigaGuideBase()"}
    @{" SetHyperHook() " Link "SetHyperHook()"}
@EndNode

@Node "AddAmigaGuideHost()" "amigaguide.library/AddAmigaGuideHost"

    NAME
	AddAmigaGuideHost - Add a dynamic node host.

    SYNOPSIS
	key = AddAmigaGuideHost ( hook, name, attrs);
	d0			  a0    d0    a1

	AMIGAGUIDEHOST key;
	struct @{"Hook" Link "utility/hooks.h/Main" 23} *hook;
	STRPTR name;
	struct @{"TagItem" Link "utility/tagitem.h/Main" 31} *attrs;

    FUNCTION
	This function adds a callback hook to the dynamic node list.

    INPUTS
	hook	- The callback hook.
	name	- Name of the AmigaGuideHost database that you are adding.
		  The name must be unique.
	attrs	- Additional attributes.  None are defined at this time.

    RETURNS
	key	- Key to be passed to @{"RemoveAmigaGuideHost()" Link "RemoveAmigaGuideHost()"} to remove a
		  dynamic node host from the system.

    EXAMPLE


	/* @{"Hook" Link "utility/hooks.h/Main" 23} dispatcher */
	ULONG __asm hookEntry(
		register __a0 struct @{"Hook" Link "utility/hooks.h/Main" 23} *h,
		register __a2 VOID *obj,
		register __a1 VOID *msg)
	{
	    /* Pass the parameters on the stack */
	    return ((h->h_SubEntry)(h, obj, msg));
	}

	ULONG __saveds
	dispatchAmigaGuideHost(struct @{"Hook" Link "utility/hooks.h/Main" 23} *h, STRPTR db, Msg msg)
	{
	    struct opNodeIO *onm = (struct opNodeIO *) msg;
	    ULONG retval = 0;

	    switch (msg->MethodID)
	    {
		/* Does this node belong to you? */
		case HM_FindNode:
		    {
			struct opFindHost *ofh = (struct opFindHost *) msg;

			kprintf("Find [%s] in %s\n", ofh->ofh_Node, db);

			/* Return TRUE to indicate that it's your node, otherwise
			 * return FALSE. */
			retval = TRUE;
		    }
		    break;

		/* Open a node. */
		case HM_OpenNode:
		    kprintf("Open [%s] in %s\n", onm->onm_Node, db);

		    /* Provide the contents of the node */
		    onm->onm_DocBuffer = TEMP_NODE;
		    onm->onm_BuffLen = strlen(TEMP_NODE);

		    /* Indicate that we were able to open the node */
		    retval = TRUE;
		    break;

		/* Close a node, that has no users. */
		case HM_CloseNode:
		    kprintf("Close [%s] in %s\n", onm->onm_Node, db);

		    /* Indicate that we were able to close the node */
		    retval = TRUE;
		    break;

		/* Free any extra memory */
		case HM_Expunge:
		    kprintf("Expunge [%s]\n", db);
		    break;

		default:
		    kprintf("Unknown method %ld\n", msg->MethodID);
		    break;
	    }

	    return (retval);
	}

	main(int argc, char **argv)
	{
	    struct @{"Hook" Link "utility/hooks.h/Main" 23} hook;
	    AMIGAGUIDEHOST hh;

	    /* Open the library */
	    if (AmigaGuideBase = OpenLibrary("amigaguide.library", 33))
	    {
		/* Initialize the hook */
		hook.h_Entry = hookEntry;
		hook.h_SubEntry = dispatchAmigaGuideHost;

		/* Add the AmigaGuideHost to the system */
		if (hh = AddAmigaGuideHost(&hook, "ExampleHost", NULL))
		{
		    /* Wait until we're told to quit */
		    Wait(SIGBREAKF_CTRL_C);

		    /* Try removing the host */
		    while (RemoveAmigaGuideHost(hh, NULL) > 0)
		    {
			/* Wait a while */
			Delay(250);
		    }
		}

		/* close the library */
		CloseLibrary(AmigaGuideBase);
	    }
	}


    SEE ALSO
	@{"RemoveAmigaGuideHost()" Link "RemoveAmigaGuideHost()"}

@EndNode

@Node "AmigaGuideSignal()" "amigaguide.library/AmigaGuideSignal"

   NAME
	AmigaGuideSignal - Obtain signal bit to Wait for an async AmigaGuide.

   SYNOPSIS
	signal = AmigaGuideSignal ( handle );
	d0			    a0

	ULONG signal;
	AMIGAGUIDECONTEXT handle;

   FUNCTION
	This function returns the signal bit to Wait on for AmigaGuideMsg's
	for a particular AmigaGuide database.

   INPUTS
	handle	- Handle to a AmigaGuide system.

   EXAMPLE

	ULONG sigw, sigh;
	AMIGAGUIDECONTEXT handle;

	/* get the signal bit to wait on for a AmigaGuide message */
	sigh = AmigaGuideSignal(handle);

	/* add the signal bit into the total signals to wait on */
	sigw |= sigh;

   RETURNS
	signal	- @{"Signal" Link "exec.hyper/Signal()"} bit to Wait on.

   SEE ALSO
	@{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}, @{"GetAmigaGuideMsg()" Link "GetAmigaGuideMsg()"}, @{"ReplyAmigaGuideMsg()" Link "ReplyAmigaGuideMsg()"}

@EndNode

@Node "CloseAmigaGuide()" "amigaguide.library/CloseAmigaGuide"

    NAME
	CloseAmigaGuide - Close a AmigaGuide client.

    SYNOPSIS
	CloseAmigaGuide ( handle );
			  a0

	AMIGAGUIDECONTEXT handle;

    FUNCTION
	Closes a synchronous, or asynchronous, AmigaGuide client.

	This function will also close all windows that were opened for
	the client.

    INPUTS
	handle	- Handle to an AmigaGuide client.

    SEE ALSO
	@{"OpenAmigaGuide()" Link "OpenAmigaGuide()"}, @{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}

@EndNode

@Node "ExpungeDataBases()" "amigaguide.library/ExpungeDataBases"

    NAME
	ExpungeDataBases - Flush all buffers for all cached databases.

    SYNOPSIS
	ExpungeDataBases ( flush );
			   d0

	BOOL flush;

    FUNCTION
	Flush the buffers for each cached AmigaGuide database.

    INPUTS
	flush	- When set to TRUE, then the databases are also closed and
		  removed from the cache list.

    SEE ALSO
	@{"OpenAmigaGuide()" Link "OpenAmigaGuide()"}, @{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}, @{"CloseAmigaGuide()" Link "CloseAmigaGuide()"}

@EndNode

@Node "ExpungeXRef()" "amigaguide.library/ExpungeXRef"

    NAME
	ExpungeXRef - Clear the cross reference table from memory.

    SYNOPSIS
	ExpungeXRef();

    FUNCTION
	This function unloads the cross reference table from memory.

    SEE ALSO
	@{"LoadXRef()" Link "LoadXRef()"}

@EndNode

@Node "GetAmigaGuideMsg()" "amigaguide.library/GetAmigaGuideMsg"

   NAME
	GetAmigaGuideMsg - Get messages from a particular AmigaGuide system.

   SYNOPSIS
	msg = GetAmigaGuideMsg ( handle );
	d0			 a0

	struct AmigaGuideMsg *msg;
	AMIGAGUIDECONTEXT handle;

   FUNCTION
	This function returns a SIPC message from the AmigaGuide system,
	if there is a message available.

   INPUTS
	handle	- Handle to a AmigaGuide system.

   EXAMPLE

	AMIGAGUIDECONTEXT handle;
	struct AmigaGuideMsg *agm;

	/* get a AmigaGuide message */
	while (agm = GetAmigaGuideMsg(handle))
	{
	    /* process the event */
	    switch (agm->agm_Type)
	    {
		case ToolCmdReplyID:	/* a command has completed */
		    if (agm->agm_Pri_Ret)
		    {
			/* An error occurred, the reason is in agm_Sec_Ret.
			 * The command string is in agm_Data
			 */
		    }
		    break;

		case ToolStatusID:	/* status message */
		    if (agm->agm_Pri_Ret)
		    {
			/* an error occurred, the reason is in agm_Sec_Ret */
		    }
		    break;

		default:
		    break;
	    }

	    /* reply to the AmigaGuide message */
	    ReplyAmigaGuideMsg(agm);
	}

   RETURNS
	msg	- Pointer to a SIPC message or NULL if no message was
		  available.

   SEE ALSO
	@{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}, @{"AmigaGuideSignal()" Link "AmigaGuideSignal()"}, @{"ReplyAmigaGuideMsg()" Link "ReplyAmigaGuideMsg()"}

@EndNode

@Node "LoadXRef()" "amigaguide.library/LoadXRef"

    NAME
	LoadXRef - Load a cross reference table.

    SYNOPSIS
	success = LoadXRef(lock,name);
	d0		   a0   a1

	LONG success;
	BPTR lock;
	STRPTR name;

    FUNCTION
	This function loads the specified cross reference table from
	disk into memory.

    INPUT
	lock	- Lock on the directory that the file resides in.  May
		  be NULL.
	name	- Name of the file to load.

    RESULT
	-1	- Indicates that the load was aborted by a ^C
	0	- Failure to load.
	1	- Successful load.
	2	- Already loaded.

    SEE ALSO
	@{"ExpungeXRef()" Link "ExpungeXRef()"}

@EndNode

@Node "LockAmigaGuideBase()" "amigaguide.library/LockAmigaGuideBase"

    NAME
	LockAmigaGuideBase - Lock an AmigaGuide client for exclusive access.

    SYNOPSIS
	key = LockAmigaGuideBase ( handle );
	d0			   a0
	LONG key
	HYPERCONTEXT handle;

    FUNCTION
	This functions locks an AmigaGuide client for exclusive access.

	So far, there is no reason for developers to make calls to this
	function, since all public functions already do the arbitration.

    INPUTS
	handle	- Handle to an AmigaGuide client.

    RETURNS
	key	- Key to be passed to @{"UnlockAmigaGuideBase()" Link "UnlockAmigaGuideBase()"} to unlock the
		  client.

    SEE ALSO
	@{"UnlockAmigaGuideBase()" Link "UnlockAmigaGuideBase()"}

@EndNode

@Node "LockE()" "amigaguide.library/LockE"

    NAME
	LockE -- Search the given environment and lock a directory or file

    SYNOPSIS
	lock  = LockE( path,  name, accessMode )
	D0	       A0     D1    D2

	BPTR lock;
	BPTR path;
	STRPTR name;
	LONG accessMode;

    FUNCTION
	A filing system lock on the file or directory 'name' is returned if
	possible.

	If the accessMode is ACCESS_READ, the lock is a shared read lock;
	if the accessMode is ACCESS_WRITE then it is an exclusive write
	lock.  Do not use random values for mode.

	If LockE() fails (that is, if it cannot obtain a filing system lock
	on the file or directory) it returns a zero.

	Tricky assumptions about the internal format of a lock are unwise,
	as are any attempts to use the fl_Link or fl_Access fields.

    INPUTS
	path	   - pointer to a path list.  If this entry is NULL,
		     then the path given in the AmigaGuide/Path environment
		     variable is searched (this variable is only loaded
		     at library open time).

		     SetEnv AmigaGuide/Path "WORK:Docs/Libs WORK:Docs/Devs"

	name	   - pointer to a null-terminated string
	accessMode - integer

    RESULTS
	lock	   - BCPL pointer to a @{"FileLock" Link "dos/dosextens.h/Main" 445}.

    SEE ALSO
	@{"dos.library/Lock()" Link "dos.hyper/Lock()"}, @{"dos.library/UnLock()" Link "dos.hyper/UnLock()"}, @{"dos.library/DupLock()" Link "dos.hyper/DupLock()"}
	@{"dos.library/ChangeMode()" Link "dos.hyper/ChangeMode()"}, @{"dos.library/NameFromLock()" Link "dos.hyper/NameFromLock()"}
	@{"dos.library/DupLockFromFH()" Link "dos.hyper/DupLockFromFH()"}

@EndNode

@Node "OpenAmigaGuide()" "amigaguide.library/OpenAmigaGuide"

    NAME
	OpenAmigaGuide - Open a synchronous AmigaGuide database.

    SYNOPSIS
	handle = OpenAmigaGuide ( nag, control );
	d0			  a0	a1

	AMIGAGUIDECONTEXT handle;
	struct NewAmigaGuide *nag;
	struct @{"MsgPort" Link "exec/ports.h/Main" 29} *control;

    FUNCTION
	Opens a AmigaGuide database, complete with the first viewing
	window, for synchronous activity.

	Before you call OpenAmigaGuide(), you must initialize a NewAmigaGuide
	structure.  NewAmigaGuide is a structure that contains all the
	information needed to open a database.  The NewAmigaGuide structure
	must be retained until the call returns.

	The function will not return until the user closes all the
	windows.

    INPUTS
	nag	- Pointer to an instance of a NewAmigaGuide structure.  That
		  structure is initialized with the following data.

		  nag_Lock
		  Lock on the directory that the database is located in.
		  Not needed if nag_Name contains the complete path name.

		  nag_Name
		  Name of the AmigaGuide database.

		  nag_Screen
		  @{"Screen" Link "intuition/screens.h/Main" 97} to open the viewing windows on, NULL for the
		  Workbench screen.

		  nag_PubScreen
		  Pointer to the name of the public screen to open on.
		  Must already be opened.

		  nag_HostPort
		  Name of the applications' ARexx port (currently not used).

		  nag_ClientPort
		  Base name to use for the databases' ARexx port.

		  nag_Flags
		  Used to specify the requirements of this database.  The
		  flags are defined in <libraries/amigaguide.h>.

		    HTF_LOAD_INDEX
		    This flag only applies to an ansynchronous open.
		    Force the index of the database to always be
		    loaded.  The AmigaGuide system maintains two date
		    stamps, one for the last time that the database was
		    opened and the other for the last time that the
		    database was accessed by the user. The hyper system
		    makes several calculations based on the current
		    date stamp and the other two date stamps to
		    determine what portions of the database need to be
		    pre-cached.

		    HTF_LOAD_ALL
		    Load the entire database, and all its nodes into
		    memory.

		    HTF_CACHE_NODE
		    Don't flush a node from memory after the user is
		    finished viewing it.

		    HTF_CACHE_DB
		    Don't remove buffers when closed.  This will cause
		    the buffers to remain until the library is
		    expunged or the @{"ExpungeDataBases()" Link "ExpungeDataBases()"} function is
		    performed.

		  nag_Context
		  NULL terminated array of context nodes, in the form of:

			/* context array */
			STRPTR context[] =
			{
			    "MAIN",
			    "INTRO",
			    "GADGETS",
			    NULL
			};

		  The context array is not copied, but referenced,
		  therefore must remain static throughout the useage of
		  the AmigaGuide system.  This array is only referenced
		  when using the @{"SetAmigaGuideContext()" Link "SetAmigaGuideContext()"} function.

		  nag_Node
		  @{"Node" Link "exec/nodes.h/Main" 23} to start at (does not work with @{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}).

		  nag_Line
		  Line to start at (does not work with @{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}).

		  nag_Extens
		  Used by V36 and beyond to pass additional arguments.

		  nag_Client
		  This is a private pointer, MUST be initialized to NULL.

	control	- SIPC control port.  This field MUST always be set to
		  NULL.

    EXAMPLE

	/* Short example showing synchronous AmigaGuide access */
	LONG ShowAmigaGuideFile (STRPTR name, STRPTR node, LONG line)
	{
	    struct NewAmigaGuide nag = {NULL};
	    AMIGAGUIDECONTEXT handle;
	    LONG retval = 0L;

	    /* Fill in the NewAmigaGuide structure */
	    nag.nag_Name = name;
	    nag.nag_Node = node;
	    nag.nag_Line = line;

	    /* Open the AmigaGuide client */
	    if ( handle = OpenAmigaGuide(&nag, NULL))
	    {
		/* Close the AmigaGuide client */
		CloseAmigaGuide(handle);
	    }
	    else
	    {
		/* Get the reason for failure */
		retval = IoErr();
	    }

	    return (retval);
	}

    RETURNS
	handle	- Handle to a AmigaGuide system.

    SEE ALSO
	@{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}, @{"CloseAmigaGuide()" Link "CloseAmigaGuide()"}, @{"ExpungeDataBases()" Link "ExpungeDataBases()"}

@EndNode

@Node "OpenAmigaGuideAsync()" "amigaguide.library/OpenAmigaGuideAsync"

   NAME
	OpenAmigaGuideAsync - Open an asynchronous AmigaGuide database.

   SYNOPSIS
	handle = OpenAmigaGuideAsync ( nag, attrs );
	d0				a0  d0

	AMIGAGUIDECONTEXT handle;
	struct NewAmigaGuide *nag;
	struct @{"TagItem" Link "utility/tagitem.h/Main" 31} *attrs;

   FUNCTION
	Opens an AmigaGuide database for ansynchronous use.

	The NewAmigaGuide structure, and its pointers, must stay valid until an
	ActiveToolID or ToolStatusID message is received by the calling
	process.

	This function actually spawns @{"OpenAmigaGuide()" Link "OpenAmigaGuide()"} as another process, so,
	for further documentation, refer to the @{"OpenAmigaGuide()" Link "OpenAmigaGuide()"} function.

   INPUTS
	nag	- Pointer to a valid NewAmigaGuide structure.
		  (see @{"OpenAmigaGuide()" Link "OpenAmigaGuide()"} for documentation on its useage).

	future	- Future expansion, must be set to NULL for now.

   RETURNS
	handle	- Handle to an AmigaGuide system.

   SEE ALSO
	@{"OpenAmigaGuide()" Link "OpenAmigaGuide()"}, @{"CloseAmigaGuide()" Link "CloseAmigaGuide()"}

@EndNode

@Node "OpenE()" "amigaguide.library/OpenE"

    NAME
	OpenE -- Search the given environemnt and open a file for IO.

    SYNOPSIS
	file = OpenE ( path, name, accessMode )
	D0	       A0    D1    D2

	BPTR file;
	BPTR path;
	STRPTR name;
	LONG accessMode;

    FUNCTION
	The named file is opened and a file handle returned.  If the
	accessMode is MODE_OLDFILE, an existing file is opened for reading
	or writing.  This call should not be used to create a file.

	The 'name' can be a filename (optionally prefaced by a device
	name), a simple device such as NIL:, a window specification such as
	CON: or RAW: followed by window parameters, or "*", representing the
	current window.  Note that as of V36, "*" is obsolete, and CONSOLE:
	should be used instead.

	If the file cannot be opened for any reason, the value returned
	will be zero, and a secondary error code will be available by
	calling the routine @{"IoErr()" Link "dos.hyper/IoErr()"}.

    INPUTS
	path	   - pointer to a path list.  If this entry is NULL,
		     then the path given in the AmigaGuide/Path environment
		     variable is searched (this variable is only loaded
		     at library open time).

		     SetEnv AmigaGuide/Path "WORK:Docs/Libs WORK:Docs/Devs"

	name	   - pointer to a null-terminated string
	accessMode - integer

    RESULTS
	file	   - BCPL pointer to a @{"FileHandle" Link "dos/dosextens.h/Main" 90}

    SEE ALSO
	@{"dos.library/Close()" Link "dos.hyper/Close()"}, @{"dos.library/ChangeMode()" Link "dos.hyper/ChangeMode()"},
	@{"dos.library/NameFromFH()" Link "dos.hyper/NameFromFH()"}, @{"dos.library/ParentOfFH()" Link "dos.hyper/ParentOfFH()"},
	@{"dos.library/ExamineFH()" Link "dos.hyper/ExamineFH()"}, @{"dos.library/Open()" Link "dos.hyper/Open()"}

@EndNode

@Node "RemoveAmigaGuideHost()" "amigaguide.library/RemoveAmigaGuideHostmigaguide.library/RemoveAmigaGuideHost"

    NAME
	RemoveAmigaGuideHost - Remove a dynamic node host.

    SYNOPSIS
	use = RemoveAmigaGuideHost ( key, attrs)
	d0		 	a0   a1

	LONG use;
	AMIGAGUIDEHOST key;
	struct @{"TagItem" Link "utility/tagitem.h/Main" 31} *attrs;

    FUNCTION
	This function removes a dynamic node host, that was added by
	@{"AddAmigaGuideHost()" Link "AddAmigaGuideHost()"}, from the system.

    INPUTS
	key	- Key that was returned by @{"AddAmigaGuideHost()" Link "AddAmigaGuideHost()"}.
	attrs	- Additional attributes.  None are defined at this time.

    RETURNS
	use	- Number of outstanding clients of this database.  You
		  can not exit until use==0.

    SEE ALSO
	@{"AddAmigaGuideHost()" Link "AddAmigaGuideHost()"}

@EndNode

@Node "ReplyAmigaGuideMsg()" "amigaguide.library/ReplyAmigaGuideMsg"

   NAME
	ReplyAmigaGuideMsg - Reply to an AmigaGuide message.

   SYNOPSIS
	ReplyAmigaGuideMsg ( msg );
			     a0

	struct AmigaGuideMsg *msg;

   FUNCTION
	This function is used to reply to an AmigaGuide SIPC message.

   INPUTS
	msg	- Pointer to a SIPC message returned by a previous call to
		  @{"GetAmigaGuideMsg()" Link "GetAmigaGuideMsg()"}.

   SEE ALSO
	@{"OpenAmigaGuideAsync()" Link "OpenAmigaGuideAsync()"}, @{"AmigaGuideSignal()" Link "AmigaGuideSignal()"}, @{"GetAmigaGuideMsg()" Link "GetAmigaGuideMsg()"}

@EndNode

@Node "SendAmigaGuideCmd()" "amigaguide.library/SendAmigaGuideCmd"

   NAME
	SendAmigaGuideCmd - Send a command string to a AmigaGuide system.

   SYNOPSIS
	success = SendAmigaGuideCmd ( handle, cmd, future );
	d0				a0    d0   d1

	BOOL success;
	AMIGAGUIDECONTEXT handle;
	STRPTR cmd;
	ULONG future;

   FUNCTION
	This function sends a command string to an AmigaGuide system.  The
	command can consist of any valid AmigaGuide action command.

	The following are the currently valid action commands:

	  ALINK <name>	Load the named node into a new window.

	  LINK <name>	Load the named node.

	  RX <macro>	Execute an ARexx macro.

	  RXS <command>	Execute an ARexx string file.  To display a picture,
			use 'ADDRESS COMMAND DISPLAY <picture name>', to
			display a text file 'ADDRESS COMMAND MORE <doc>'.

	  CLOSE		Close the window (should only be used on windows
			that were started with ALINK).

	  QUIT		Shutdown the current database.

   INPUTS
	handle	- Handle to an AmigaGuide system.
	cmd	- Command string.
	future	- Future expansion, must be set to NULL for now.

   EXAMPLE

	/* bring up help on a particular subject */
	SendAmigaGuideCmd(handle, "LINK MAIN", NULL);

   RETURNS
	success	- Returns TRUE if the message was sent, otherwise returns
		  FALSE.

   SEE ALSO
	@{"SetAmigaGuideContext()" Link "SetAmigaGuideContext()"}

@EndNode

@Node "SendAmigaGuideContext()" "amigaguide.library/SendAmigaGuideContextgaguide.library/SendAmigaGuideContext"

   NAME
	SendAmigaGuideContext - Align an AmigaGuide system on the context ID.

   SYNOPSIS
	success = SendAmigaGuideContext ( handle, future );
	d0				  a0	  d0

	BOOL success;
	AMIGAGUIDECONTEXT handle;
	ULONG future;

   FUNCTION
	This function is used to send a message to an AmigaGuide system to
	align it on the current context ID.

	This function effectively does a:

	    SendAmigaGuideCmd(handle 'LINK ContextArray[contextID]', NULL);

   INPUTS
	handle	- Handle to an AmigaGuide system.
	future	- Future expansion, must be set to NULL for now.

   EXAMPLE

	struct @{"IntuiMessage" Link "intuition/intuition.h/Main" 676} *imsg;

	...

	case RAWKEY:
	    switch (imsg->Code)
	    {
		case 95:
		    /* bring up help on a particular subject */
		    SendAmigaGuideContext(handle, NULL);
		    break;
		...
	    }
	    break;

	...

   RETURNS
	success	- Returns TRUE if the message was sent, otherwise returns
		  FALSE.

   SEE ALSO
	@{"SetAmigaGuideContext()" Link "SetAmigaGuideContext()"}, @{"SendAmigaGuideCmd()" Link "SendAmigaGuideCmd()"}

@EndNode

@Node "SetAmigaGuideContext()" "amigaguide.library/SetAmigaGuideContextmigaguide.library/SetAmigaGuideContext"

   NAME
	SetAmigaGuideContext - Set the context ID for an AmigaGuide system.

   SYNOPSIS
	success = SetAmigaGuideContext ( handle, context, future );
	d0				 a0	    d0	     d1

	BOOL success;
	AMIGAGUIDECONTEXT handle;
	ULONG context;
	ULONG future;

   FUNCTION
	This function, and the @{"SendAmigaGuideContext()" Link "SendAmigaGuideContext()"} function, are used to
	provide a simple way to display a node based on a numeric value,
	instead of having to build up a slightly more complex command
	string.

   INPUTS
	handle	- Handle to an AmigaGuide system.
	context	- Index value of the desired node to display.
	future	- Future expansion, must be set to NULL for now.

   EXAMPLE

	/* sample context table */
	STRPTR ContextArray[] =
	{
	    "MAIN",
	    "FILEREQ",
	    "PRINT",
	    "ABOUT",
	    NULL
	};

	/* quickie defines */
	#define	HELP_MAIN	0
	#define	HELP_FILEREQ	1
	#define	HELP_PRINT	2
	#define	HELP_ABOUT	3

	...

	struct NewAmigaGuide nag = {NULL};

	/* initialize the context table */
	nag.nag_Context = ContextArray;

	...

	/* bring up help on a particular subject */
	SetAmigaGuideContext(handle, HELP_ABOUT, NULL);

   RETURNS
	success	- Returns TRUE if a valid context ID was passed,
		  otherwise returns FALSE.

   SEE ALSO
	@{"SendAmigaGuideContext()" Link "SendAmigaGuideContext()"}, @{"SendAmigaGuideCmd()" Link "SendAmigaGuideCmd()"}

@EndNode

@Node "UnlockAmigaGuideBase()" "amigaguide.library/UnlockAmigaGuideBasemigaguide.library/UnlockAmigaGuideBase"

    NAME
	UnlockAmigaGuideBase - Unlock a locked AmigaGuide client.

    SYNOPSIS
	UnlockAmigaGuideBase ( key );
				d0
	LONG key;

    FUNCTION
	This functions unlocks a locked AmigaGuide client.

	So far, there is no reason for developers to make calls to this
	function, since all public functions already do the arbitration.

    INPUTS
	key	- Key returned by @{"LockAmigaGuideBase()" Link "LockAmigaGuideBase()"}.

    SEE ALSO
	@{"LockAmigaGuideBase()" Link "LockAmigaGuideBase()"}

@EndNode

@Node "SetHyperHook()" "hyper.library/SetHyperHook"

   NAME
	SetHyperHook - Initialize a callback hook.  *** OBSOLETE ***

   SYNOPSIS
	success = SetHyperHook ( handle, kind, hook, data);
	d0			 a0	 d0    a1    a2

	LONG success;
	HYPERCONTEXT handle;
	LONG kind;
	VOID (*hook)();
	VOID **data;

   FUNCTION
	This function is used to establish a client callback hook for
	the HyperText library.

   INPUTS
	handle	- Handle to a hypertext system.
	kind	- Kind of hook to install.

		HTH_OPEN
		Function to be called to get access to a new node.

		HTH_CLOSE
		Function to be called to terminate access to a node.

	hook	- A pointer to the function to call.  A NULL hook can
		  be specified to turn off a hook.

	data	- A pointer to the data to pass to the function. Should
		  be the same for each hook, but can be different.

   RETURNS
	success	- TRUE if the hook was installed, FALSE if there was
		  a failure.

   BUGS
	Don't use these functions.  They are obsolete.  Instead use the
	new calls, @{"AddHyperHost()" Link "hyper.hyper/AddHyperHost()"} and @{"RemoveHyperHost()" Link "hyper.hyper/RemoveHyperHost()"}.

   SEE ALSO
	@{"AddHyperHost()" Link "hyper.hyper/AddHyperHost()"}, @{"RemoveHyperHost()" Link "hyper.hyper/RemoveHyperHost()"}

@EndNode

