Using an Item

Once an item is created or opened, you can manage it with the kernel item calls, which are described here.

Finding an Item

To find an item by specifying its item type and a set of tag arguments or a name, use these calls.

Item FindItem( int32 cType, const TagArg *tp )

Item FindItemVA( int32 cType, uint32 tags, ...)

Item FindNamedItem( int32 cType, const char *name )

Item FindVersionedItem( int32 cType, const char *name, uint8 vers,  uint8 rev )

FindItem() accepts an item type value, which is created by MkNodeID() as it is for the CreateItem() call. This value specifies the type of the item for which the call should search. The second argument, tp, is a pointer to an array of tag arguments the call should try to match. When the call is executed, it looks through the list of items and, if it finds an item of the specified item type whose tag arguments match those set in the tag argument array, it returns the item number of that item.

FindNamedItem() calls FindItem() after creating a TagArg for the name. When it searches through the item list, it checks names of all items of the specified type. If it finds a match, it returns the item number of that item.

FindVersionedItem() accepts cType as its first argument, which is the same type of value as itemType in the other find calls. It also accepts a name, a version number, and a revision number. It searches to find the item that matches these specifications, then returns the item number of that item.

All of the item finding calls return a negative number if an error occurred in the search.

Getting a Pointer to an Item

To find the absolute address of an item, use this call:

void *LookupItem( Item i )

LookupItem() takes the item number of the item to locate as its only argument. If it finds the item, it returns a pointer to the item's ItemNode structure; if it doesn't find the item, it returns NULL. Once you have a pointer to the item, you can use it to read the values in the fields of the data structure. The ItemNode structure is protected by the system, so a user task can't write to it.

Checking If an Item Exists

To see if an item exists, use this call:

void *CheckItem( Item i, uint8 ftype, uint8 ntype )

CheckItem() accepts the item number of the item you want to check, followed by the folio type and the node type of the item. (ftype and ntype are the same as the arguments accepted by MkNodeID(), and are supplied with constants defined in appropriate header files.) When executed, the call returns a NULL if it can't find an item with the specified item number, or if it found an item but it didn't have the specified folio and node types. If the call finds an item that matches in all respects, it returns a pointer to that item.

Changing Item Ownership

To change the ownership of an item from one task to another, use this call:

Err SetItemOwner( Item i, Item newOwner )

The first argument of SetItemOwner() is the item number of the item for which to change ownership; its second argument is the item number of the task that is to be the new owner. The task that makes this call must be the owner of the item. If ownership transfer fails, the call returns a negative number (an error code).

When ownership of an item changes, the item is removed from the former owner's resource table and placed in the new owner's resource table. This allows an item to remain in the system after the original owner dies; all items owned by a task are removed from the system when the task dies.

Changing an Item's Priority

To change the priority of an item, a task should call:

int32 SetItemPri( Item i, uint8 newpri )

Item priority determines how frequently system resources are allocated to an item. The higher its priority, the more often an item has access to the resources. The task must be the owner of the item to change its priority.

SetItemPri() accepts the item number of the item whose priority you want to change, followed by an unsigned 8-bit integer which specifies the new priority for the item. Priority values range from 0-255. The call returns the former priority value of the item if successful, otherwise it returns a negative number.