Life cycle binding functions

The life cycle binding functions are the service specific functions called by Natural Access to perform:

The dispatcher invokes the life cycle binding functions in response to Natural Access application calls. The life cycle binding functions can return SUCCESS, SUCCESS_RESPONSE, or an error.

Note: The service writer is not required to implement all life cycle binding functions.

Most life cycle binding functions are synchronous functions with two exceptions: xxxOpenService, which initializes the managed resource by requesting resources to support a client, and xxxCloseService, which releases resources. These functions provide a return code indicating initialization success or failure. The actual results of the functions return later as events.

The following illustration shows the binding functions called in response to Natural Access application startup:

Life cycle binding functions -- startup

The following illustration shows the binding functions called in response to Natural Access application shutdown:

Life cycle binding functions -- shutdown

The following tables list the life cycle binding functions and give an overview of each function including the key dispatcher functions and data structures:

Life cycle binding functions: registration

xxxInitializeManager

Description:   

  • Acts as an entry point into service manager for service manager and service registration.

  • Declares version numbers for service manager.

  • Declares compatibility levels for service manager.

  • Declares service manager binding functions.

  • Acquires global tracemask pointer managed by ctdaemon (if active).

Behavior:

Synchronous

Dispatcher functions called:

dispRegisterServiceManager

dispGetTracePointer

Important data structure:

CTAINTREV

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaInitialize

Required?

Must be implemented.


xxxDefineService

Description:   

  • Declares version numbers for service.

  • Declares compatibility levels for service.

  • Declares needed API compatibility levels of related services.

  • Declares the parameter descriptor tables.

Behavior:

Synchronous

Dispatcher functions called:

dispRegisterService

Important data structure:

CTAINTREV

CTAPARM_DESC

CTAREQ_SVC

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaInitialize

Required?

Must be implemented.


Life cycle binding functions: event handling

xxxAttachServiceManager

Description:   

  • Declares wait objects (if interacting with a multiplexed managed resource).

  • Initializes communications with managed resource.

  • Allocates queuecontext object for processing incoming events.

Behavior:

Synchronous

Dispatcher functions called:

dispRegisterWaitObject

Important data structure:

Managed resource specific queuecontext.

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaCreateQueue

Required?

Optional, required if managed resource is multiplexed.


xxxDetachServiceManager

Description:   

Deallocates all data structures allocated with xxxAttachServiceManager.

Behavior:

Synchronous

Dispatcher functions called:

dispUnregisterWaitObject

Important data structure:

Managed resource specific queuecontext.

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaDestroyQueue

Required?

Must be implemented if xxxAttachServiceManager is implemented.


Life cycle binding functions: service startup

xxxOpenServiceManager

Description:   

  • Allocates mgrcontext object, which contains data pertaining to the managed resource but is specific to a context.

  • Declares wait objects (if interacting with a non-multiplexed managed resource).

Behavior:

Synchronous

Dispatcher functions called:

dispRegisterWaitObject

dispGetQueueHandle

Important data structure:

Managed resource specific mgrcontext.

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaOpenServices

Required?

Must be implemented.


xxxOpenService

Description:   

Initializes the managed resource by requesting resources to support a client (for example, a context).

Behavior:

Asynchronous

Dispatcher functions called:

dispQueueEvent or dispMakeAndQueueEvent

dispAddRTC (optional)

dispRegisterRTCAlias (optional)

Important data structures:

CTA_MVIP_ADDR

CTA_SERVICE_ARGS

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaOpenServices

Required?

Optional


xxxAddRTC

Description:   

Actions taken by the service when this function is called is at the discretion of the service writer.

Behavior:

Synchronous

Dispatcher functions called:

Service specific

Important data structure:

Service specific

Returns:

SUCCESS

Initiated through the Natural Access dispatcher:

dispAddRTC

Required?

Optional


Life cycle binding functions: service shutdown

xxxCloseServiceManager

Description:   

Deallocates all data structures allocated with xxxOpenServiceManager.

Behavior:

Synchronous

Dispatcher functions called:

dispUnregisterWaitObject

Important data structure:

Managed resource specific mgrcontext.

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaCloseServices

Required?

Must be implemented.


xxxCloseService

Description:   

Releases resources from managed resource for that context.

Behavior:

Asynchronous

Dispatcher functions called:

dispQueueEvent or dispMakeAndQueueEvent

dispRemoveRTC (optional)

dispUnregisterRTCAlias (optional)

Important data structure:

None

Returns:

SUCCESS or an error.

Initiated through Natural Access function call:

ctaCloseServices

Required?

Must be implemented if xxxOpenService is implemented.


xxxRemoveRTC

Description:   

Actions taken by the service when this function is called is at the discretion of the service writer.

Behavior:

Synchronous

Dispatcher functions called:

Service specific

Important data structure:

Service specific

Returns:

SUCCESS

Initiated through Natural Access dispatcher function:

dispRemoveRTC

Required?

Optional