# 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 | Buffer is NULL, or size is 0.
CTAERR_BAD_SIZE | Descriptor buffer is too small.
CTAERR_INVALID_CTAHD | An invalid context handle was passed as an argument to a function, or the context was destroyed by another thread.
CTAERR_NOT_IMPLEMENTED | Function is not available in the execution mode associated with the specified context.
CTAERR_NOT_INITIALIZED | Natural Access is not initialized. Call ctaInitialize first.

#### Details

ctaGetObjDescriptor 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 or a service object). Applications attach to existing contexts by invoking ctaAttachContext and specifying the descriptor. Applications attach to existing service objects by invoking ctaAttachObject and specifying the descriptor.

When creating the context as a short cut for the descriptor, the application can specify a context name of up to 11 characters long (for example, common). Natural Access can automatically generate the descriptor and the application can obtain the descriptor later using 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 provides 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 Sharing service objects for more information.

#### See also

ctaCreateContextEx

#### 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;
}