INtime SDK Help
LookupRtHandle
INtime SDK v7.1 > About INtime > INtime Kernel > Object Directories > LookupRtHandle

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

Note: If the hProcess parameter refers to a reference object, then the returned handle will also be for a reference object. The reference object adds to the process' object count and should be deleted when finished with.

RTHANDLE LookupRtHandle(
    RTHANDLE hProcess,       // handle for RT process
    LPSTR lpszName,          // pointer to object's catalog name
    DWORD dwMilliseconds     // number of ticks to wait for object
);

Parameters

hProcess
Handle for a process. A value of NULL_RTHANDLE may be used to indicate the current process.
lpszName
Pointer to an ASCII, zero-terminated string containing the name of the object. The name must be at most 12 characters long (excluding the trailing zero). The lookup is performed in a case-sensitive fashion.
dwMilliseconds
The number of milliseconds the calling thread waits:
NO_WAIT The thread does not wait.
WAIT_FOREVER The thread waits for its request to be fully satisfied.
1-655349 Calling thread goes to sleep for this many milliseconds, after which it awakes.

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

Return Values

A handle for the returned object.
Success.
BAD_RTHANDLE
Failure. To determine the status, call GetLastRtError.

Status

E_TIME 0x0001
One of these conditions exist:
  • No RT handle was available during the waiting period specified in dwMilliseconds.
  • The specified object directory is not full and the thread cannot wait.
E_LIMIT 0x0004
The specified object directory is full and specified object is not yet cataloged.
E_EXIST 0x0006
One or more of these conditions exist:
  • You used an invalid value for hProcess.
  • The name was found, but the cataloged object has a NULL_RTHANDLE.
E_TYPE 0x8002
hProcess requires an RT 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
lpszName is invalid.
E_CONTEXT
The global handle is for a reference object.
E_INVALID_ADDRESS 0x00E2
The object cataloged is a reference handle from a different node and cannot be safely returned.

Requirements

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/rtbase.h rt.h rt.lib
   
See Also

Global objects