5.1 Introduction

5.2 Creating the Header Files

5.2.1 Defining the API Function Prototypes

5.2.2 Defining the API Function Command Codes

5.2.3 Defining Error Codes

5.2.4 Defining Event and Reason Codes

5.2.5 Defining the Trace Tags

5.3 Writing the API Function Code

5.3.1 Calling the SPI Function

5.3.2 Error Handling Macros

5.3.3 Example API Function

5.4 Declaring Parameters

5.4.1 Creating the Parameter Definition File

5.4.2 Generating the Parameter Files

5.1 Introduction

Implementing the API for a service includes creating:

• Header files that contains the API function prototypes, error and event codes, and command code definitions.

• Source file that contains the API implementation.

• Parameter source file (.pf) that lists parameters and their attributes.

The following files should be created when implementing the service API:

File	Description
xxxapi.c	Implements the service API by calling the corresponding SPI function and handling API errors.
xxxdef.h	Contains API prototypes, event and error definitions, and public data structures.
xxxparm.pf	ASCII definition of each parameter and hierachical structure.
xxxparm.c	Parameter source file automatically generated from xxxparm.pf.
xxxparm.h	Parameter header file automatically generated from xxxparm.pf.
xxxsys.h	Internal header file containing API command codes.

5.2 Creating the Header Files

When implementing the API, the following information is declared in the service's header files:

• API function prototypes

• API function command codes

• Error codes

• Event and reason codes

• Trace tag codes

5.2.1 Defining the API Function Prototypes

Each API function prototype is defined in xxxdef.h including a description of the function and its arguments. API functions must follow the API coding conventions described in Section 3.6, Natural Access Coding Conventions.

tik service

<<<< excerpt from tikdef.h >>>> /*---------------------------------------------------------- Request Tick strings to be generated (i.e., start the ticker). Operation of this API call is asynchronous. ctahd: Handle for CT Access context to start. start: Timer start parameter structure includes: * a count field specifying the number of tick strings * a frequency field specifying how often to send tick strings. ---------------------------------------------------------*/ DWORD NMSAPI tikStartTimer( CTAHD ctahd, TIK_START_PARMS *start ); /*---------------------------------------------------------- Request termination of Tick strings (i.e., stops a running ticker). Operation of this API call is asynchronous. ctahd: Handle for CT Access context. -------------------------------------------------------*/ DWORD NMSAPI tikStopTimer( CTAHD ctahd );

5.2.2 Defining the API Function Command Codes

Each service API function is assigned a command code in xxxsys.h. The command codes are placed in the .sys header file as opposed to the .def header file because the information is not publicly needed. The command code is constructed by using the service ID, the CTA_CODE_COMMAND type code, and a sequence number:

  (( service_id << 16 ) | CTA_CODE_COMMAND | sequence )

tik service	<<<< excerpt from tiksys.h >>>> /* tik command codes are constructed using this formula: */ /* (( TIK_SVCID<<16) | CTA_CODE_COMMAND | SEQUENCE ) */
	#define TIKCMD_START #define TIKCMD_STOP #define TIKCMD_GET_CHANNEL_INFO	0x403000 0x403001 0x403002

To facilitate browsing, the defines are typically assigned to the resultant hexadecimal number rather than constructed.

5.2.3 Defining Error Codes

Each service API error is assigned an error code in xxxdef.h. The error code is constructed by using the service ID, the CTA_CODE_ERROR type code, and a sequence number:

  (( service_id << 16 ) | CTA_CODE_ERROR | sequence )

tik service	<<<< excerpt from tikdef.h >>>> /* tik error codes are constructed using this formula: */ /* (( TIK_SVCID<<16) | CTA_CODE_ERROR | SEQUENCE ) */
	TIKERR_COMM_FAILURE TIKERR_CHANNEL_NOT_OPENED TIKERR_OWNER_CONFLICT TIKERR_UNKNOWN_SERVER_RESPONSE TIKERR_CAN_NOT_CONNECT	0x400001 0x400002 0x400003 0x400004 0x400005

5.2.4 Defining Event and Reason Codes

Each service API event is assigned an event code in xxxdef.h. The event code is constructed by using the service ID, the CTA_CODE_EVENT type code, and a sequence number:

  (( service_id << 16 ) | CTA_CODE_EVENT | sequence )

tik service	<<<< excerpt from tikdef.h >>>> /* tik event codes are constructed using this formula: */ /* (( TIK_SVCID<<16) | CTA_CODE_EVENT | SEQUENCE ) */
	TIKEVN_TIMER_TICK TIKEVN_TIMER_DONE	0x402001 0x402002

Each reason is assigned a reason code in xxxdef.h. The reason code is constructed by using the service ID, the CTA_CODE_REASON type code, and a sequence number:

  (( service_id << 16 ) | CTA_CODE_REASON | sequence )

tik service	<<<< excerpt from tikdef.h >>>> /* tik reason codes are constructed using this formula: */ /* (( TIK_SVCID<<16) | CTA_CODE_REASON | SEQUENCE ) */
	TIK_REASON_TIMER_DONE TIK_REASON_INVALID_CHANNEL TIK_REASON_CHANNEL_ACTIVE TIK_REASON_UNKNOWN_SERVER_REASON	0x401001 0x401002 0x401003 0x401004

5.2.5 Defining the Trace Tags

Service-specific trace tags are declared in xxxsys.h. The trace tag is constructed by using the service ID, the CTA_CODE_TRACETAG type code, and a sequence number:

  (( service_id << 16 ) | CTA_CODE_TRACETAG | sequence )

tik service
	<<<< excerpt from tiksys.h >>>> /* tik trace tag codes are constructed using this formula: */ /* (( TIK_SVCID<<16) | CTA_CODE_TRACETAG | SEQUENCE ) */ #define TIK_TRACETAG_CMD 0x404001 #define TIK_TRACETAG_RSP 0x404002 #define TIK_TRACETAG_BIT0 0x404003

5.3 Writing the API Function Code

The xxxapi.c file contains the service API functions. Each API function calls a corresponding SPI function then logs any errors returned using the Natural Access error macros. Figure 22 shows the flow of a command initiated by an application API call:

Figure 22. Service API call to SPI Function

5.3.1 Calling the SPI Function

The signature of an SPI function is typically identical to that of its associated API function with one exception. The SPI function contains an additional parameter to indicate the invoker of the SPI function (an application or another service). Since an API function is only invoked by an application, each API function calls the SPI function using CTA_APP_SVCID.

5.3.2 Error Handling Macros

To ensure consistent error handling for all Natural Access services, the service API function should use the Natural Access error macros for reporting API errors. The Natural Access error macros expand to calls to dispApiError.

The macro CTAAPIERROR is called with an error code and the API function name:

  #define CTAAPIERROR (ctahd, err) dispApiError((ctahd), (err),\
        (funcname,  NULL)

CTAAPIERRORINFO also includes an additional information string to further qualify the error:

  #define CTAAPIERRORINFO (ctahd, err,info)dispApiError((ctahd),\
         (err),  funcname, info)

The Natural Access error macros must be called by API functions when an error is returned so that the dispatcher can invoke the application registered error handler and log a trace message to the ctdaemon.

To use the error macros, the service API function must include a call to the macro CTABEGIN with the function name. This macro defines a local variable funcname that stores the function name that is passed to dispApiError when the other error macros are invoked.

5.3.3 Example API Function

tik service

<<<< excerpt from tikapi.c >>>> /*------------------------------------------------------------- tikStartTimer - Tik service API function to start timer function on TICK server -------------------------------------------------------------*/ DWORD NMSAPI tikStartTimer( CTAHD ctahd, TIK_START_PARMS *start) { DWORD ret ; /* Needed by CTAAPIERROR */ CTABEGIN( "tikStart" ) ; /* Call corresponding SPI function with CTA_APP_SVCID */ ret = tikSpiCmdStartTimer( ctahd, start, CTA_APP_SVCID ) ; /* Log error on failure */ if ret != SUCCESS ) { CTAAPIERROR( ctahd, ret ) ; } return ret ; }

5.4 Declaring Parameters

The following files contain the service parameters:

File	Description
xxxparm.pf	ASCII definition of each parameter and hierachical structure.
xxxparm.c	Parameter source file automatically generated from xxxparm.pf during the make process.
xxxparm.h	Parameter header file automatically generated from xxxparm.pf during the make process.

5.4.1 Creating the Parameter Definition File

The parameter definition file (.pf file) specifies the service name, service ID, the parameter category, and the parameter name. The following table provides an overview of the .pf file. Refer to the Natural Access Developer's Reference Manual for more details on constructing and using a .pf file.

Field	Description
SvcName	The service name is specified via the keyword SvcName followed by the actual service name.
SvcID	The service ID is specified via the keyword SvcID.
Category	A category block is specified with the keyword Category followed by the name of the category being declared. A category block is terminated with the keyword End. Category category_name field_descriptor or substructure . End
SubStructure	A substructure block is specified with the keyword SubStructure followed by the name of the substructure being declared. A substructure block is terminated with the keyword End. SubStructure substructure_ name field_descriptor . End
FieldDescriptor	A field descriptor can only be declared within a Category or SubStructure block. A FieldDescriptor specification does not begin with a keyword. It begins with the name of the field itself. name, type, unit, default value · name: A field name must be unique within its scope (e.g., there can only be one busycount field within the CALLPROG category. However, there could also be a busycount field in the COLLECT category. A field name is not case sensitive (e.g., CALLPROG.busycount and CALLPROG.busyCount are duplicates). · type: A field descriptor must contain a data type. The supported data types are: WORD, DWORD, INT16, INT32, STRING · unit: A field descriptor must also contain a units specification. Supported units are: INTEGER, COUNT, MASK, HZ, MS, DB, DBM, IDU, PERCENT The STRING units specification must be used when the field data type is a string. When declaring a STRING, you must also declare a maximum string size (in bytes). The declared maximum size must be sufficient to store the default string. · default: A field descriptor must contain a default value. String values must be surrounded by double quotes. Integer values may either be entered in hex or decimal format.

tik service

<<<< excerpt from tikparm.pf >>>> #------------------------------------------------------------- # NAME: tikparm.pf # This file defines (ASCII format) the TIK Service parameters # that are accessible via the CT Access API parameter functions. # This file is used by the pf_tosrc conversion program to $ generate the following 'C' files: tikparm.h and tikparm.c #------------------------------------------------------------- SvcName TIK # TIK Service Name SvcId 0x40 # TIK Service ID # Only one category (two fields) is required by the TIK service; # The TIK parameters (usable via CT Access) are: # tik.start.NumTicks # tik.start.Frequency Category Start NumTicks, DWORD, COUNT, 2 # number of tick strings rcvd. Frequency, DWORD, COUNT, 2 # frequency of tick strings rcvd End

5.4.2 Generating the Parameter Files

The parameter files, xxxparm.c and xxxparm.h, are automatically generated from the parameter file (.pf) using the utility pf2src.

To generate the source file for the .pf file, enter:

  pf2src pf_file

pf_file is the .pf input file.

The generated header file, xxxparm.h, defines the service ID assigned to the service and the API level parameter data structures on a per category basis. Each parameter structure uses the naming convention _PARMS as described in Section 3.6.8, Parameter Structure Naming Convention.

tik service	<<<< excerpt from tikparm.h >>>> /* file generated via pf2src tikparm.pf */ #define TIK_SVCID 0x40 #define TIK_START_PARMID 0x400001 typedef struct { DWORD size; DWORD NumTicks; DWORD Frequency; } TIK_START_PARMS;

In the generated xxxparm.c, file the parameter description tables are declared and a pointer to the tables is created. The pointer to the parameter descriptor table must be included in the call to dispRegisterService during service initialization (see Section 7.4.2, xxxDefineService).

tik service

<<<< excerpt from tikparm.c >>>> /* file generated via pf2src tikparm.pf */ #include <nmstypes.h> #include <ctadisp.h> #include <tikparm.h> TIK_START_PARMS _tikStartDefaults = { 12, 2, 2, }; #define _F_(f,s,u) CTAFIELDDESC(TIK_START_PARMS,f,s,u) const CTAPARM_FIELD _tikStartStructDef[] = { "START", 0, 12 , 0, 0, _F_( NumTicks, DWORD, COUNT ), _F_( Frequency, DWORD, MS ), }; #undef _F_ CTAPARM_DESC _tikStartParmDescr = { TIK_START_PARMID, &_tikStartDefaults, _tikStartStructDef, CTAPARM_FIELDCNT(_tikStartStructDef) }; const CTAPARM_DESC * const _tikParmDescTable[] = { &_tikStartParmDescr, NULL };