dispRegisterService

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

Prototype

DWORD dispRegisterService ( const char *svcname, unsigned svcid, const char *svcmgrname, const CTAINTREV_INFO *previnfo, const CTAREQSVC_INFO *preqsvc [], unsigned nreqsvcs, const CTAPARM_DESC *const *stdparmdesc, const CTAPARM_DESC *const *extparmdesc)

Argument

Description

svcname

Pointer to the name of the service.

svcid

Service identifier used in commands, errors, reasons, and events (assigned by NMS).

svcmgrname

Pointer to the service manager name.

previnfo

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

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

preqsvc

Pointer to array of structures containing information on services required by this service:

typedef struct
{
   char *svcname;     /* Name of required service.             */
   DWORD svcid;       /* Service ID of required service.       */
   DWORD reqspilevel; /* Required compat level of Service SPI  */
} CTAREQSVC_INFO;

nreqsvcs

Number of required service structures in preqsvc.

stdparmdesc

Pointer to an array of pointers to standard parameter descriptors that are managed for the service by Natural Access. The array is terminated with a NULL character. Each parameter descriptor structure in the array has the following definition:

typedef struct
{
   DWORD parm_id;
   void *parm;                 /* Pointer to defaults (binary) */
   const CTAPARM_FIELD *descr; /* Pointer to field descriptor  */
   DWORD fieldcnt;             /* Number of fields in descr    */
} CTAPARM_DESC;

Field descriptors have the following definition:

typedef struct
{
   char  *name;  /* Name of the field.                         */
   DWORD offset; /* Byte offset from base or # of fields       */
                 /* if received zero (0) in array.             */
   DWORD size;   /* Size of the field.                         */
   DWORD format; /* Format specifier.                          */
   DWORD units;  /* Units specifier.                           */
} CTAPARM_FIELD;

Note: These structures are automatically generated by pf2src from a .pf file.

extparmdesc

Pointer to an array of pointers to non-standard (extension) parameter descriptors that are managed for the service by Natural Access. The array is terminated with a null character. The structure is defined in stdparmdesc.


Return values

Return value

Description

SUCCESS

 

CTAERR_ALREADY_INITIALIZED

ctaInitialize was already called by the application.

CTAERR_BAD_ARGUMENT

Function argument has an invalid value or a required pointer argument is NULL.

CTAERR_DUPLICATE_EXTPARMS

External parameters must be unique.

CTAERR_INCOMPATIBLE_PARMS

Standard parameters did not match.

CTAERR_INCOMPATIBLE_REVISION

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

CTAERR_OUT_OF_MEMORY

Unable to allocate memory.

CTAERR_SHAREMEM_ACCESS

Failed to access shared memory.


Details

dispRegisterService registers a service with the Natural Access dispatcher at initialization time. This registration includes establishing the parameters that Natural Access manages for the service. This function must be called for every service that provides an API to a Natural Access application. It is typically called from xxxDefineService.

Parameter descriptor tables are used directly by Natural Access and are not copied. They must remain accessible in the process address space throughout the lifetime of the process that initialized Natural Access. Parameter default values are copied to shared memory if this call is made within ctdaemon. In application processes, the defaults are taken either from shared memory or directly from the defaults registered with the parameter descriptor tables. Parameter default values must also remain accessible to Natural Access as long as the process is active.

Revision information is used to verify dispatcher compatibility. It is also available for checking the compatibility of the application API and the service SPI. The SPI compatibility level is used to verify that other services that make calls to this service (services that have this service listed in its list of required services) expect the same SPI. The required service list indicates the list of services whose SPIs are used by this service.