# Sharing contexts

Applications can share contexts. To create shared contexts, use ctaCreateContextEx. ctaCreateContextEx requires the same parameters as ctaCreateContext with an additional flag that sets the service sharing mode. The service sharing mode determines how processes attached to a common object can use the service instances opened on that context. When creating shared contexts, ensure that the context names are unique to the specified server.

When a client application destroys a shared context (with ctaDestroyContext), it relinquishes control of the context resources. However Natural Access waits until every application using the context invokes ctaDestroyContext before destroying the context.

This topic provides information about:

- Service sharing modes

- Creating persistent contexts

- Attaching to shared contexts

## Service sharing modes

When two applications share a context, they can both use service instances opened on the context. However, depending on the sharing mode in which the context was created, the processes may or may not be able to immediately use functions and receive events from the open services. Natural Access provides two modes of service sharing:

- Common access

- Declared access

### Common access

In common access mode (the default mode), service instances opened on a context by one application can be used immediately by any other application that attaches to the context. In common access mode, applications do not need to use ctaOpenServices to open service instances already active on the context. An application that closes a service on the context (with ctaCloseServices) closes the services for all applications that share the context.

The following illustration shows two applications sharing a context created in common access mode. Application 1 creates the context and opens the ADI service and the Voice Messaging (VCE) service on the context. Application 2 attaches to the context and can immediately access the ADI service and VCE service instances opened on the context.

### Declared access

In declared access mode, each application opens and closes its own service instances as needed. When an application attaches to the context, no services are available until the application opens them, even if other applications sharing the context have opened service instances. If the application closes a particular service instance, it is closed only for that application. Any other application that opened the service on the shared context can continue using it.

The following illustration shows two applications sharing a context created in declared access mode. Application 1 creates the context and opens the ADI service and Voice Messaging (VCE) service on the context. Application 2 attaches to the context and opens services on the context.

### Comparing common access and declared access modes

Common access mode and declared access mode have the following similarities:

- Single instance of shared service.

- Events are broadcasted to all clients holding handles to the shared context.

- A context is destroyed on the local server only when the last remaining client invokes ctaDestroyContext.

The following table describes the differences between common access and declared access modes:

Common access mode | Declared access mode
--- | ---
When calling ctaCloseServices from one application, the service is not available to all remaining applications holding handles to the shared context. | When calling ctaCloseServices from one application, the service is still available to all remaining applications holding handles to the shared context.
Upon invocation of ctaAttachContext, all opened services are immediately available for use (services are inherited). | Upon invocation of ctaAttachContext, no services are available for immediate use. Must explicitly invoke ctaOpenServices.
Events from all inherited non-masked services are visible. | Only events from services that were explicitly opened are visible.

### Examples

The following illustration shows the process for sharing services in common and declared access modes:

The following table describes the process for each mode:

Mode | Process
--- | ---
Common access | Application 1 creates a context. When Application 2 attaches to the context with ctaAttachContext, it does not need to explicitly open services already used by Application 1 (in this case, the ADI service). Since closing a service in common access mode closes it for all other applications that share the context, Application 1 uses ctaDestroyContext to relinquish control of the context, but does not invoke ctaCloseServices. The service remains available to Application 2.
Declared access | Application 1 creates the context. When Application 2 attaches to the context, it must invoke ctaOpenServices to use Natural Access services, including services already opened on the context (such as the ADI service). To relinquish control of the context, Application 1 uses ctaCloseServices and ctaDestroyContext. The ADI service still remains available to Application 2.

Note: In either mode, Natural Access does not actually destroy the context until both Application 1 and Application 2 destroy it.

You can decide the service-sharing mode based on the application's requirements. For example, if you use one application to set up and tear down calls (with the NCC service), and another to perform play and record functions (with the VCE service), create contexts in declared access mode. Each application deals exclusively with a particular Natural Access service and does not need to access other services.

## Creating persistent contexts

When a Natural Access application creates a context, other applications can attach to the context. By default, if the originating application is disconnected after creating the context but before a second application attaches to the context, the server destroys the context. If the second application tries to attach to the context, the context does not exist. To enable the second application to attach to the context in this situation, the first application can set the CTA_CONTEXT_PERSISTENT flag in ctaCreateContextEx. The shared context continues to exist on the server even when the originating application is disconnected. Connected applications can reattach to the shared context.

When the last application attached to the context calls ctaDestroyContext, the context ceases to exist. Unless the last application calls ctaDestroyContext, the context remains active indefinitely.

## Attaching to shared contexts

Attach to existing contexts with ctaAttachContext. When invoking ctaAttachContext, specify a ctaqueuehd returned by ctaCreateQueue, and a Natural Access object descriptor. ctaAttachContext returns an application specific ctahd.

The following process shows one application creating a context and a second application attaching to the context:

Stage | Description
1 | The first application creates a context with ctaCreateContextEx.
2 | The application retrieves the context-specific object descriptor by invoking ctaGetObjDescriptor with the ctahd returned by ctaCreateContextEx.
3 | The originating application passes the object descriptor to a second application using one of the following methods: Application events using the ctaQueueEvent function. (Refer to Service sharing on a local server: csplayrc.) Since events are broadcast to all applications that share the context, use the event of a well-known named context to pass the descriptor to all attached applications. Private IPC channel. Set up a private communication channel to pass information between the applications. File. Save the context descriptor in a file. Other applications can read the descriptor from the file when they share an existing context.
4 | A second application attaches to the context by invoking ctaAttachContext and supplying the object descriptor and an event queue handle. ctaAttachContext returns an application specific ctahd.

The following illustration shows the process of creating and attaching to a shared context: