Creates a reference object from a LOCATION and an RTHANDLE for a valid object on the node indicated by the LOCATION value and returns a RTHANDLE for the reference object.

#include <rt.h>

RTHANDLE CreateRtReferenceObject(
    LOCATION hLoc, 
    RTHANDLE hObject
);

Parameters

hLoc

The location of the target object.

hObject

The value of the handle of the target object.

Remarks

This call is analogous to ntxImportRtHandle. It must be used to convert an RTHANDLE from another node if the process is to access that object.

If a reference already exists for the remote object and that reference is owned by the calling process then the same handle is returned from this call.

If this is a new reference, and if the remote object has a reference counter, then that is incremented. A new object is created which counts against the object count for the local process. When the process has finished with the handle it must be explicitly deleted using DeleteRtReferenceObject.

This call may not be used to create a reference to a reference object.

Return Values

An RTHANDLE for a reference object if the hObject value is a valid handle for an object at location indicated by LOCATION.

Success.

BAD_RTHANDLE

Failure. The function sets GetLastRtError to one of these values:

E_INVALID_ADDR	The LOCATION parameter does not refer to a valid node.
E_EXIST	The object handle does not refer to a valid object on the node indicated by the LOCATION parameter.
E_PARAM	The LOCATION parameter is not a valid location value.
E_RESOURCE_LIMIT	Insufficient resources are available to signal the remote node.
E_SLOT	The maximum number of objects on the local node has been exceeded.
E_MEM	Insufficient physical memory is available to create the reference object.
E_TYPE	The handle passed as hObject is a handle for a reference object.

Requirements