# 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.