xxxOpenService

Called when a service is opened.

Prototype

DWORD xxxOpenService (CTAHD ctahd, void *mgrcontext, char *svcname, unsigned svcid, CTA_MVIP_ADDR *mvipaddr, CTA_SERVICE_ARGS *svcargs)

Argument	Description
ctahd	Context handle.
mgrcontext	Pointer to the data structure containing information about the managed resource for a specific context returned by xxxOpenServiceManager.
svcname	Pointer to the name of the service to open.
svcid	Identifier of the service to open.
mvipaddr	Pointer to the MVIP address structure: typedef struct { DWORD board; DWORD bus; DWORD stream; DWORD timeslot; DWORD mode; } CTA_MVIP_ADDR;
svcargs	Pointer to service-specific arguments: typedef struct { char strarg [40]; DWORD args [10]; } CTA_SERVICE_ARGS;

Return values

SUCCESS or any service-specific error code.

Events

CTAEVN_DISP_OPEN_SERVICE_DONE

The event value field contains the open services completion status. The value should be set to CTA_REASON_FINISHED if the service was successfully opened.

Any other value means the service failed to open.

Details

xxxOpenService is invoked when a service is opened on a context using ctaOpenServices. mgrcontext is used to reference the context- specific memory created when the service manager was opened with xxxOpenServiceManager.

The MVIP_ADDR structure conveys the address of a resource to the device service. This is typically some form of DSP resource associated with the service being opened. For AG boards, it is the board number and local or MVIP stream and timeslot of the DSP port associated with the ADI service.

Other resources that may be required by the service can be specified in the service specific arguments. It is the responsibility of the service to define the meaning of the fields of the CTA_SERVICE_ARGS structure.

If the service makes use of RTC notifications, xxxOpenService can set up the notifications using dispAddRTC and dispRegisterRTCAlias.

xxxOpenService is asynchronous (it should return immediately), but ctaOpenServices waits for the completion event to be returned by the service before continuing to open services or return a completion event to the application. The value field of the completion event is set to CTA_REASON_FINISHED if the function completed successfully. If it is set to any other reason or error code, ctaOpenServices closes all services it was in the process of opening and returns the error to the application in the completion event.

Services that do not require asynchronous open service processing must queue CTAEVN_DISP_OPEN_SERVICE_DONE using dispQueueEvent. Otherwise, ctaOpenServices hangs.

Note: If this function returns an error, there is no asynchronous event expected and xxxCloseService is not called. If an error is returned asynchronously in the completion event, xxxCloseService is called. The service must clean up any resources it allocated in the process of opening the service.

For more information about this function, refer to Starting services.