GCNListSend()

word	GCNListSend(
        ManufacturerID		manufID,						/* manufacturer of list */
        word		listType,						/* notification type */
        EventHandle		event,						/* event to be sent to list */
        MemHandle		dataBlock,						/* data block, if any */
        word		gcnListSendFlags);						/* GCNListSendFlags */

This routine sends a message to all objects in the specified GCN list. The message is specified in event , and the list is specified in manufID and listType . The message will be sent asynchronously (some time after the change has occurred) by the message queue.

The dataBlock parameter contains the memory handle of an extra data block to be sent with the notification, if any; this block should also be specified in the classed event. If no data block is required, pass a NullHandle. If a data block with a reference cound is used, increment the reference count by one before calling this routine; this routine decrements the count and frees the block if the count reaches zero.

The gcnListSendFlags parameter is of type GCNListSendFlags , which has only one meaningful flag for this routine:

GCNLSF_SET_STATUS: Causes the message sent to the GCN list to be set as the lists "status." The list's status message is then sent to any object adding itself to the list at a later time. If this flag is set, the event handle in event will be returned by the routine. If this flag is not set, the return value will be the number of messages sent out.

Include: gcnlist.goh

GCNListSendToBlock()

word	GCNListSendToBlock(
        ManufacturerID		manufID,				/* manufacturer id of list */
        word		listType,				/* notification type */
        EventHandle		event,				/* event to be sent to list */
        MemHandle		dataBlock,				/* data block, if any */
        MemHandle		mh,				/* handle of locked LMem block
						 * containing GCN list of lists */

        ChunkHandle		listOfLists,				/* chunk of list of lists */
        GCNListSendFlags		flags);				/* GCNListSendFlags */

This routine sends the specified event to the specified list, just as GCNListSend() . GCNListSendToBlock() , however, specifies a particular instance of the GCN list by specifying the appropriate list of lists in mh and listOfLists . Other parameters and return values are identical to GCNListSend() .

See Also: GCNListSend().

Include: gcnlist.goh

GCNListSendToList()

void	GCNListSendToList(
        optr		list,				/* optr of GCN list */
        EventHandle		event,				/* event to send to list */
        MemHandle		dataBlock,				/* handle of data block, if any */
        GCNListSendFlags		flags);				/* GCNListSendFlags */

This routine sends the specified event to the specified GCN list . The list is specified explicitly by optr as opposed to by manufacturer ID and type. The event will be sent via the proper queues to all objects registered on the list. After the notification is handled by all notified objects, the event will be freed, as will the data block passed. (If no data block, pass NullHandle in dataBlock )

The flags parameter can have one flag, GCNLSF_SET_STATUS. If this flag is set, the event passed will be set as the list's status message.

Include: gcnlist.goh

See Also: GCNListSend().

GCNListSendToListHandles()

void	GCNListSendToListHandles(
        MemHandle		mh,				/* handle of list's block */
        ChunkHandle		ch,				/* chunk of list */
        EventHandle		event,				/* event to send to list */
        MemHandle		dataBlock,				/* handle of data block, if any */
        GCNListSendFlags		flags);				/* GCNListSendFlags */

This routine is exactly the same as GCNListSendToList() ; the list is specified not by optr, however, but by a combination of its global and chunk handles.

See Also: GCNListSendToList().

Include: gcnlist.goh

GCNListUnRelocateBlock()

Boolean	GCNListUnRelocateBlock(
        MemHandle		mh,				/* handle of the locked lmem block
						 * containing the list of lists */

        ChunkHandle		listOfLists,				/* chunk of the list of lists */
        MemHandle		relocBlock);				/* handle of block containing
						 * relocation/unrelocation info */

This routine unrelocates the specified list of lists, updating all the optrs according to the information in relocBlock . This routine is rarely, if ever, used by applications; it is used primarily by the UI when shutting down to a state file.

It returns true if the specified list of lists has no lists saved to state and therefore is simply destroyed. The return value is false if the list of lists is saved to the state file normally.

Include: gcnlist.goh