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. To obtain the handle of the root process, call ntxGetRootRtProcess.

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

Visual Basic:

Sub ntxCatalogNtxHandle(
  ByVal hRtProcess As Integer,
  ByVal hRtObject As Integer,
  ByVal lpszName As String)

Visual C#:

void ntxCatalogNtxHandle (
  Int32 hRtProcess,
  Int32 hRtObject,
  String 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

A string containing the catalog name of the object. The name must be at most 12 characters long (excluding the trailing zero).

Remarks

Because an object may have several names, several entries for a single object may exist in a directory. However, only one object may be cataloged under a given name in a given object directory. If another thread is waiting for the object to be cataloged, that thread wakes when the entry is cataloged.

INtimeException Status

E_LIMIT

The specified object directory is full.

E_CONTEXT

The specified object directory already contains the name being cataloged.

E_EXIST

You used an invalid value for hRtObject or hRtProcess.

E_TYPE

hRtProcess does not contain a process handle.

E_PARAM

lpszName contains a string with a length of 0 (zero) or greater than 12.

Requirements

See Also

INtimeDotNet system calls, Object directory system calls, LookupRtHandle