# Creating the header files

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

- API function prototypes

- API function command codes

- Error codes

- Event and reason codes

- Trace tag codes

## Defining the API function prototypes

Define each API function prototype in xxxdef.h. Include a description of the function and its arguments. API functions must follow the API coding conventions described in 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 Natural 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 Natural Access context.
-------------------------------------------------------*/
DWORD NMSAPI tikStopTimer( CTAHD ctahd );

## Defining the API function command codes

Assign each service API function a command code in xxxsys.h. The command codes are placed in the .sys header file because the information is not publicly needed. Construct the command code 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 0x403000
#define TIKCMD_STOP 0x403001
#define TIKCMD_GET_CHANNEL_INFO 0x403002

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

## Defining error codes

Define each service API error an error code in xxxdef.h. Construct the error code 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 0x400001
TIKERR_CHANNEL_NOT_OPENED 0x400002
TIKERR_OWNER_CONFLICT 0x400003
TIKERR_UNKNOWN_SERVER_RESPONSE 0x400004
TIKERR_CAN_NOT_CONNECT 0x400005

## Defining event and reason codes

Assign each service API event an event code in xxxdef.h. Construct the event code 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 0x402001
TIKEVN_TIMER_DONE 0x402002

Assign each reason a reason code in xxxdef.h. Construct the reason code 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 0x401001
TIK_REASON_INVALID_CHANNEL 0x401002
TIK_REASON_CHANNEL_ACTIVE 0x401003
TIK_REASON_UNKNOWN_SERVER_REASON 0x401004

## Defining the trace tags

Declare service-specific trace tags in xxxsys.h. Construct the trace tag 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