INtime SDK Help
CatalogRtHandle
INtime SDK v6 > About INtime > INtime Kernel > Object Directories > CatalogRtHandle

Names an object in a process directory.

Use the CatalogRtHandle system call to put the object into an object directory. You specify the process in which to catalog the object, the object's handle, and a name for the object.

You can catalog the object in the thread's process or in any process for which you have the handle. Each process has an object directory, including the root process. To make an object accessible to all threads in the system, catalog it in the root process. Call GetRtThreadHandles to obtain the handle of the root process.

You can use any byte values except null in the name. You can catalog the object under several different names, all with the same handle, if your application needs this. The INtime kernel returns a status code if you try to catalog an object using a name already cataloged in the directory.

BOOLEAN CatalogRtHandle(
    RTHANDLE hProcess,    // handle for RT process
    RTHANDLE hObject,     // handle for object to be cataloged
    LPSTR lpszName        // pointer to object name
);

Parameters

hProcess
Handle for an RT process. A value of NULL_RTHANDLE may be used to indicate the current process.
hObject
Handle for an RT object to be cataloged. A NULL handle is allowed.
lpszName
Pointer to an ASCII, zero-terminated string containing the catalog name of the object. The name must be at most 12 characters long (excluding the trailing zero).

Remarks

There may be several entries for a single object in a directory, because the object may have several names. However, in a given object directory, only one object may be cataloged under a given name. If another thread is waiting, using LookupRtHandle, for the object to be cataloged, that thread is awakened when the entry is cataloged.

If the hProcess parameter refers to a reference object, then the hObject parameter must also refer to a reference object where both refer to objects on the same host.

Return Values

TRUE
Success.
FALSE
Failure. To determine the status, call GetLastRtError.

Status

E_OK 0x0000
No exceptional conditions occurred.
E_LIMIT 0x0004
The specified object directory is full.
E_CONTEXT 0x0005
The specified object directory already contains the name being cataloged.
E_EXIST 0x0006
You used an invalid value for hObject or hProcess.
E_TYPE 0x8002
A process cannot use hProcess as an RT handle.
E_PARAM 0x8004
lpszName contains a string with a length of 0 (zero) or greater than 12.
E_BAD_ADDR 0x800F
lpszName is invalid.
E_INVALID_ADDR 0x00E2
The address provided for the remote object is not a valid address, or the objects referred to by hProcess and hObject are on different nodes.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib
   
See Also