Opening services

This topic describes how to open services. It also includes information about Attaching to service objects and includes an Example of support for CPU failover.

Description of opening services

Applications open services on a context by calling ctaOpenServices and passing a context handle and a list of service descriptors. The service descriptor specifies the name of the service, the service manager, and service-specific arguments (for example, MVIP address).

The call to ctaOpenServices is asynchronous and returns immediately. When all services are open, a CTAEVN_OPEN_SERVICES_DONE event is returned to the application.

Any application attached to a shared context can open service instances on the shared context (not just the application that created the context). However, whether the applications that share the context can immediately use the service instance depends on the service sharing mode specified with ctaCreateContextEx.

When applications attach to shared contexts in declared mode, they are not required to pass service-specific information to the call to ctaOpenServices. For example, the ADI service requires board, stream, and timeslot information when the context is created. Subsequent applications attaching to the context do not need to pass this information. If the information is present, it is ignored.

Opening a service on a context creates a service instance. A service instance holds the data that represents the specific use of the service, for example, the board and stream being used. The context is a bound collection of service instances; this binding associates a server, services, and resources with a state, creates service dependencies, and handles parameter management.

From the context handle (ctahd), Natural Access Server (ctdaemon) can locate specific service instance information. Applications do not directly address the service; they call a service function with the context handle. For example, the API command, vceOpenFile (ctahd...), opens a voice file using the VCE service instance opened on the context.

Natural Access supports opening and closing services on an as-needed basis to optimize the use of scarce resources. Once the services are open, as shown in the following illustration, all paths in Natural Access are defined. You can now use the service API.

Note: Applications can use only the services specified on the server on which the context is created.

Opening services

Attaching to service objects

Once a service is open on a shared context, applications can share the service objects associated with the context. Each application determines how to share a service object depending on the service implementation.

To enable applications to share service objects, each application must attach to the same context, service instance, and service object. Applications can use one of the following methods to share service objects:

• Natural Access function calls
  Applications exchange object descriptors and then explicitly attach to the service object using a Natural Access function call.

• Service-specific function calls
  Applications use a service-specific function call to attach to the service object.

• Events
  Applications are automatically attached to the service object after receiving a service-specific event.

Natural Access function calls

Natural Access provides the function ctaGetObjDescriptor to retrieve the object descriptor associated with a specific service object. By using any standard transport mechanism, an application then transfers service object descriptors to all peer applications. When an application receives the service object descriptor, it attaches to the service object using the ctaAttachObject function call. This function is provided by Natural Access and is available to all services.

The following procedure describes how to use an object descriptor to attach to a service object.

1. The first application creates a context, and the second application attaches to the same context. Refer to Attaching to shared contexts for more information.

2. The first application creates a service object on the shared context with a service function such as nccPlaceCall.

3. The application retrieves the object-specific descriptor by invoking ctaGetObjDescriptor with the object handle (objhd) returned by nccPlaceCall.

4. The originating application passes the object descriptor to the second application.

5. The second application invokes ctaAttachObject and supplies the object descriptor. ctaAttachObject returns a service-specific object handle (objhd) that is unique from the one given to the originating application.
   
   After obtaining the object handle, the second application can access the attached service object as can the first application, and both applications can share the service object.
   
   

Using object descriptors to attach service objects

Service-specific function calls

The following procedure describes how an application attaches to service objects by invoking service-specific functions. The Natural Call Control service supports this method. Refer to the Natural Call Control Service Developer's Reference Manual for more information.

1. The first application creates a context, and the second application attaches to the same context. Refer to Attaching to shared contexts for more information.

2. The first application creates a service object on the shared context with a service function such as nccPlaceCall.

3. The second application provides a buffer to accept call handles while invoking a service-specific function such as nccGetLineStatus.
   
   .

Using a list of object handles to attach service objects

Events

Since applications attached to the context receive all the events regardless of whether they are attached to the service object, an application can receive an unsolicited event containing a service object handle to which it is not currently attached. Upon receiving the event, the service object is attached to the context automatically. (Natural Access and some services provide this support.) Applications can take the object handle from the objHd field in CTA_EVENT to access the shared object.

The Natural Call Control (NCC), Digital Trunk Monitor (DTM), and MSPP services support this method. Refer to the Natural Call Control Service Developer's Reference Manual, Digital Trunk Monitor Service Developer's Reference Manual, or Fusion Support for CPU Failover for more information.

The following procedure describes how an application is automatically attached to a service object:

1. The first application creates a context.

2. The second application attaches to the same context. Refer to Attaching to Shared Contexts for more information.

3. The second application invokes ctaWaitEvent to receive events.

4. When an event arrives, the second application reads the service object handle from the objHd field in a service-specific event and uses the service object handle to access the attached service object. Both applications now share the same service object. Certain services require parameter settings. Refer to the service-specific manual for more information.

Using unsolicited events to attach service objects

Example of support for CPU failover

Natural Access applications can interact with multiple instances of Natural Access Server (ctdaemon) to share resources. By using shared contexts and shared object handles, independent applications can share responsibility for overseeing and managing service resources. If one of the applications fails, a backup application can continue processing with no interruption of service.

The following procedure describes how two cooperating client applications communicate with each other through a shared context over a dedicated private IPC channel. The client applications and Natural Access Server (ctdaemon) can run in either the same host or in separate hosts.

For an example of sharing control of a service object, refer to Sharing service objects: takeover.

Note: To restore processing between the first application and the Natural Access Server, reopen the applicable context and service objects and use the ctaAttachContext and ctaAttachObject functions to reconnect to them.

The following illustration shows an example of applications configured for CPU failover.

Setting up CPU failover applications