ctaGetObjDescriptor

Retrieves the Natural Access object descriptor associated with the specified context or object handle.

Prototype

DWORD ctaGetObjDescriptor ( CTAHD hd, char *descriptor, DWORD size)

Argument	Description
hd	Service object handle or context handle
descriptor	Pointer to a buffer to receive the Natural Access object descriptor in text format.
size	Size of the descriptor buffer.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	The buffer is NULL, or size is 0.
CTAERR_BAD_SIZE	The size of the buffer is too small.
CTAERR_INVALID_CTAHD
CTAERR_NOT_IMPLEMENTED	This function is not available in the execution mode associated with the specified context.
CTAERR_NOT_INITIALIZED	Natural Access is not initialized. Call ctaInitialize first.

Events

None.

Details

This function returns the full path of the object descriptor associated with the specified context or object handle.

A descriptor is a character string that uniquely identifies a Natural Access processing resource (for example, a context, a service object). Applications attach to existing contexts by invoking ctaAttachContext and specifying the descriptor. Applications invoke ctaAttachObject and specify the descriptor to attach to existing service objects.

The application that creates the context can

Specify a context name (up to 11 characters) when creating the context as a short cut for the descriptor. For example, common.
Let Natural Access automatically generate the descriptor. The application can obtain the descriptor later with ctaGetObjDescriptor. The following table shows the format of the returned descriptor:

Context object	Service object
[prot://][host]ctx_name	[prot://][host]ctx_name/svc_obj_name

The following table shows examples of valid descriptors:

Descriptor example	Description
cta://localhost/common	ctx_name (common) is user-specified.
cta://127.0.0.1/0x80010001	ctx_name (0x80010001) is automatically generated by Natural Access.
context	Descriptor contains only the context name. The host part of the descriptor defaults depending on the application mode.
localhost/context_name	A context created in a Natural Access Server process that is separate from the application, but on the same host.

To access a shared resource, applications can transfer descriptors from one application to another.

Refer to Attaching to shared contexts and Attaching to service objects for more information.

Example

case PAIR( 'D', 'H' ):              /* GET CONTEXT DESCRIPTOR */
    {
        char descriptor[128];

        if ( ctaGetObjDescriptor(ctahd, descriptor, 128) == SUCCESS )
            printf("Descriptor = %s\n", descriptor);
        else
            printf("Unable to get descriptor for ctahd 0x%x\n", ctahd);

        break;
    }