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

Searches the given process's object directory for a given name and returns the object handle, if found. The calling thread can wait for the object to be cataloged if not present at the time of the call.

Use ntxLookupNtxHandle to get an object's handle so a thread can access the object. You specify the handle of the process whose object directory you want to search, the name of the object and the amount of time the thread can wait. If the object is not cataloged, the thread goes to sleep by waiting for the specified time or until the name is cataloged, whichever comes first.

NTXHANDLE ntxLookupNtxhandle(
    NTXHANDLE hRtProcess,
    LPSTR lpszName,
    DWORD dwMilliseconds
);

Parameters

hRtProcess
Handle to the RT process whose directory will be examined.
lpszName
Null-terminated string.
dwMilliseconds
The number of milliseconds the calling thread waits:
NO_WAIT The thread does not wait.
INFINITE The thread waits for its request to be fully satisfied.
Any positive integer Calling thread goes to sleep for this many milliseconds, after which it awakes.

Note: The kernel converts milliseconds to high-level ticks.

Return Values

The handle associated with the specified name.
Success.
NTX_BAD_NTXHANDLE
Failure. To determine the status, call ntxGetLastRtError.

Status

E_OK 0x0000
No exceptional conditions occurred.
E_TIME 0x0001
One of these is true:
  • No object was available during the waiting period specified in dwMilliseconds.
  • The thread was not willing to wait, and the entry indicated by lpszName is not in the specified object directory.
E_LIMIT 0x0004
The specified object directory is full and the object being looked up is not yet cataloged.
E_CONTEXT 0x0005
The specified process has an object directory of size 0 (zero).
E_EXIST 0x0006
At least one of these is true:
  • hRtProcess (if not a null selector) is not a handle for an existing object.
  • The name was found, but the cataloged object has a null handle.
E_TYPE 0x8002
The process parameter is not a handle for a process.
E_PARAM 0x8004
lpszName contains a string with a length of 0 (zero) or greater than 12.
E_BAD_ADDR 0x800F
The pointer to lpszName is invalid.
E_NTX_INTERNAL_ERROR
The DLL could not contact the RT kernel to complete the request.

Requirements

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