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