Retrieves the Natural Access object descriptor associated with the specified context or object handle.
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 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. |
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.
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;
}