dispRegisterServiceManager

Registers a service manager with the Natural Access dispatcher at initialization time.

Prototype

DWORD dispRegisterServiceManager (const char *svcmgrname, CTASVCMGR_FNS *svcmgrfns, const CTAINTREV_INFO *previnfo)

Argument

Description

svcmgrname

Pointer to the name of the service manager.

svcmgrfns

Pointer to the service manager binding functions. This structure has the following definition:

typedef DWORD (NMSSTDCALLPTR PFUNC)();

typedef struct _CTASVCMGR_FNS
    {
    DWORD size;
    DWORD (NMSSTDCALLPTR xxxDefineService)(
       char *svcname);

    DWORD (NMSSTDCALLPTR xxxAttachServiceManager)(
     CTAQUEUEHD ctaqueuehd, unsigned mode, void **queuecontext);

    DWORD (NMSSTDCALLPTR xxxDetachServiceManager)(
     CTAQUEUEHD ctaqueuehd, void *queuecontext);

    DWORD (NMSSTDCALLPTR xxxOpenServiceManager)(
     CTAHD ctahd, void *queuecontext, void **mgrcontext);

    DWORD (NMSSTDCALLPTR xxxCloseServiceManager)(
     CTAHD ctahd, void *mgrcontext);

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

    DWORD (NMSSTDCALLPTR xxxCloseService)(
     CTAHD ctahd, void *mgrcontext, char *svcname, 
     unsigned svcid);

    DWORD (NMSSTDCALLPTR xxxProcessEvent)(
     CTAHD ctahd, void *mgrcontext, DISP_EVENT *ctaevt);

    DWORD (NMSSTDCALLPTR xxxProcessCommand)(
     CTAHD ctahd, void *mgrcontext, DISP_COMMAND *ctaevt);

    /****** for future use ******/
    DWORD (NMSSTDCALLPTR xxxAddRTC)(
     CTAHD ctahd, void *mgrcontext,
     RTC_CONDITION *rtccondition, RTC_ACTION *rtcaction);

    /****** for future use ******/
    DWORD (NMSSTDCALLPTR xxxRemoveRTC)(
     CTAHD ctahd, void *mgrcontext,
     RTC_CONDITION *rtccondition, RTC_ACTION *rtcaction);

    const char * (NMSSTDCALLPTR xxxGetText)(
     unsigned code);

    DWORD (NMSSTDCALLPTR xxxFormatMessage)(
     DISP_MESSAGE *pmsg, char *msgtext, unsigned size, 
     char *indent);

    DWORD (NMSSTDCALLPTR xxxSetTraceLevel)(
     CTAHD ctahd, void *mgrcontext, unsigned svcid, 
     unsigned tracemask);

    DWORD (NMSSTDCALLPTR xxxFormatTraceBuffer)(
     unsigned tracetag,
     void *inbuffer, unsigned insize,
     char *outbuffer, unsigned outsize);

    /****** for future use ******/
    PFUNC (NMSSTDCALLPTR xxxGetFunctionPointer)(
     unsigned ordinal);

} CTASVCMGR_FNS;

previnfo

Pointer to the service manager revision information structure containing the following fields:

typedef struct
{
 DWORD size;          /* size of the returned structure        */
 DWORD majorrev;      /* major revision of service/manager     */
 DWORD minorrev;      /* minor revision of service/manager     */
 char builddate [12]; /* build date, "mmm dd yyyy\0"           */
 DWORD reqdisplevel;  /* Required compat level of dispatcher   */
 DWORD expapilevel;   /* Exported compat level of srvce API    */
 DWORD expspilevel;   /* Exported compat level of srvce SPI    */
} CTAINTREV_INFO ;


Return values

Return value

Description

SUCCESS

 

CTAERR_ALREADY_DEFINED

Service manager that you are trying to register is already defined.

CTAERR_ALREADY_INITIALIZED

ctaInitialize was already called by the application.

CTAERR_BAD_ARGUMENT

Required pointer argument is NULL.

CTAERR_INCOMPATIBLE_REVISION

Service manager is incompatible with the revision of Natural Access that is being used.

CTAERR_OUT_OF_MEMORY

Unable to allocate memory for the queue, the driver, or the context.


Details

dispRegisterServiceManager is called by a service manager at initialization time to register a service manager and its binding functions with the Natural Access dispatcher. Once this is done, the service manager is completely specified from the point of view of Natural Access.

The only exported entry that must be provided by the service manager DLL is xxxInitializeManager (for example, vceInitializeManager for the Voice Message service). xxxInitializeManager is called by ctaInitialize the first time the service manager is loaded into the process address space. After the service manager is registered with Natural Access, xxxDefineService is invoked on all the services managed by the service manager and is listed in the arguments to ctaInitialize.

Binding functions can be specified as NULL in the list provided to the dispatcher. In this case, the dispatcher substitutes its own default binding function for the missing service manager binding function. These default binding functions translate to no operations and allow the dispatcher to always call a binding function whether one is specified by the service manager or not.