Names an object in a process directory.

Use ntxCatalogNtxHandle to put the handle into an object directory. You specify the process in which to catalog the object, the object's handle, and a name for the object. If the object directory is full, the thread receives an E_LIMIT status code.

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 ntxGetRootRtProcess 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.

NTXSTATUS ntxCatalogNtxHandle( 
    NTXHANDLE hRtProcess, 
    NTXHANDLE hRtObject, 
    LPSTR lpszName
);

Parameters

hRtProcess

Handle for an RT process. The value NTX_NULL_NTXHANDLE may be used to indicate the current process.

hRtObject

Handle for the RT object you want to catalog.

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.

Return Values

E_OK

Success.

The status code.

Failure.

Status

E_OK 0x0000

No exceptional conditions occurred.

E_LIMIT x0004

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 hRtObject or hRtProcess.

E_TYPE 0x8002

hRtProcess does not contain a process 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.

Requirements