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

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

Versions Defined in Include Link to
INtime 3.0 intime/nt/include/ntx.h ntx.h ntxext.lib
INtime 4.01 (64-bit Windows) intime/nt/include/ntx.h ntx.h ntxext64.lib
See Also