SERVICEDESC structure

Contains all the configuration information needed to run the service. It must be initialized before installation so that the kernel can configure the internal resources ready for use.

This structure:

Provides a set of fields to set up the service data structures at initialization time.
Serves as a reference object for generic code handling in certain service-related functions.

All fields up to LocalAddress must be initialized. The LocalAddress field may be initialized later if required using SetRtServiceAttributes. To use any service-dependent fields, you must define those fields as part of the service_info field and initialize as required, and the value of the wExtraSize field must be initialized correctly.

The header file includes special cases of this structure for interrupt, polled, and port services.

Syntax

typedef struct tagServiceDesc {

    char cName[14];

    WORD wServiceFlags;

    WORD wPortCreationMask;

    WORD wAddressSize;

    WORD wControlMessageSize;

    WORD wMaxTransactionBuffers;

    WORD wMaxControlBuffers;

    WORD wPortTableSize;

    WORD wNullPortID;

    WORD wFirstValidPortID;

    WORD wLastValidPortID;

    WORD wFirstAllocPortID;

    WORD wLastAllocPortID;

    LPPROC pInitialize;              WORD    _reserved_1;

    LPPROC pGetAttributes;           WORD    _reserved_2;

    LPPROC pSetAttributes;           WORD    _reserved_3;

    LPPROC pCreatePort;              WORD    _reserved_4;

    LPPROC pDeletePort;              WORD    _reserved_5;

    LPPROC pVerifyAddress;           WORD    _reserved_6;

    LPPROC pSendMessage;             WORD    _reserved_7;

    LPPROC pGetFragment;             WORD    _reserved_8;

    LPPROC pCancelTransaction;       WORD    _reserved_9;

    LPPROC pUpdateReceiveInfo;       WORD    _reserved_10;

    LPPROC pFinish;                  WORD    _reserved_11;

    LPPROC pService;                 WORD    _reserved_12;

    DWORD dwServiceThreadStackSize;  WORD    _reserved_13;

    RTHANDLE hServiceObject;

    GENADDR LocalAddress;

    LPVOID _reserved_14[14];

    WORD wExtraSize;

} SERVICEDESC, *LPSERVICEDESC;

Fields

cName

The name of the service, used by CreateRtPort to identify the service where the port is created. Name lookup is case-sensitive, and names should be padded with spaces or zeros on the right, and otherwise contain no other spaces. No terminating null character is required. Each service descriptor must have a name unique on the local system.

wServiceFlags

This field is a 16-bit word with the following format:

You can use these masks:

FL_SHORT_CIRCUIT_ONLY
FL_ALLOW_SHORT_CIRCUIT
FL_ADDRESSED
FL_ALLOW_FRAGMENTS
FL_ALLOW_RSVP
FL_LATE_INIT
FL_TYPE_MASK. The FL_TYPE_MASK field can have one of these values:
FL_GENERIC_TYPE
FL_INTERRUPT_TYPE
FL_POLLED_TYPE
FL_PORT_TYPE

`FL_GENERIC_TYPE`	The kernel does no extra actions to support the service being developed. The developer is responsible for creating the service thread and interface object.
`FL_INTERRUPT_TYPE`	The kernel creates an interrupt task using the extra fields in the INTERRUPTSERVICEDESC structure. These fields allow the kernel to create a default interrupt handler and thread. The thread calls the user's service handler when the interrupt handler signals the thread.
`FL_POLLED_TYPE`	The kernel creates a kernel alarm event and a default service thread. When the alarm event is signaled the service thread calls the user's service handler. The kernel uses the extra fields in the ALARMSERVICEDESC structure to create the alarm event and service thread.
`FL_PORT_TYPE`	The kernel creates a port object using the extra fields in the PORTSERVICEDESC structure. It also creates a service thread which calls ReceiveRtMessage on the port. Whenever a message arrives the service thread calls the user's service handler. If the FL_LATE_INIT bit is set, the service will not call the Initialize handler until the first time CreateRtPort is called for this service. If the bit is clear then the Initialize handler is called during the call to InstallRtServiceDescriptor. If the FL_ALLOW_RSVP bit is set, the call SendRtMessageRSVP is allowed. If the bit is clear, any such call will fail with a status of E_NOT_CONFIGURED. The FL_ALLOW_FRAGMENTS bit controls access to ReceiveRtFragment. If the bit is clear, any such call for this service results in a failure status of E_NOT_CONFIGURED. If the FL_ADDRESSED bit is set, the service expects to process address fields. If it is clear, and attempt is made to the system call ConnectRtPort, it will fail; field checking on the address field in other calls is ignored. If the bit is set, and no address field is passed to any of the send message calls they will fail. The FL_ALLOW_SHORT_CIRCUIT and FL_SHORT_CIRCUIT_ONLY bits are reserved for future use, and will control system support for automatic short-circuit delivery of messages.

wPortCreationMask

This field is misnamed. It is not actually a mask. It defines the default number of tranactions assigned to a port when it is created. See CreateRtPort for details.

wAddressSize

For addressed services (the FL_ADDRESSED bit in the service flags is set) this field contains the size in bytes of an address. For example, for an NIC service using standard 48-bit MAC addresses the value of this field would be 6. This value is used in address field validation and comparison by the kernel.

wControlMessageSize

Set this field to the maximum size of a control message in bytes to be handled by this service.

The kernel uses this value for validation purposes and for allocating the control message pool.

wMaxTransactionBuffers

Set this field to the maximum number of transaction buffers to be managed by the service. This value is used to set the size of the transaction buffer pool. This value also determines the total number of concurrent transactions that can be processed by the service, at all ports.

wMaxControlBuffers

Set this field to the maximum number of control buffers to be managed by the service.

wPortTableSize

The kernel maintains a table of all the port handles opened in the service, indexed by the port ID. This field should normally be set to 0 to indicate the maximum size of table. If desired to restrict the range of the port IDs, then this field may be set to another value. All port IDs start at 0 (zero) regardless (see discussion of ID allocation in the next section).

wNullPortID, wFirstValidPortID, wLastValidPortID, wFirstAllocPortID, wLastAllocPortID

These fields determine how port IDs are allocated by this service. When a port is created, a port ID value is passed to the kernel. The resulting action is determined by this algorithm:

If the port ID is in the range wFirstValidID ≤ port ID ≤ wLastValidID and the entry in the port table for that ID is empty, then the port is created with that ID. If the entry is not empty the creation fails with status E_PORT_ID_USED.

If the port ID matches the value in wNullPortID the kernel allocates the next free value in the range wFirstAllocPortID ≤ port ID ≤ wLastAllocPortID. If there is not a value available the creation fails with status E_LIMIT.

If the port ID is any other value, then the creation fails with status E_PARAM.

If it is desired to disable the auto-allocation of port IDs then make sure that the wNullPortID value falls within the valid port ID range.

If it is desired to only have the auto-allocation of port IDs then set the value of wFirstValidPortID to be greater than wLastValidPortID. In this case the user must always supply the value of wNullPortID when creating a port.

pInitialize, pGetAttributes, pSetAttributes, pCreatePort, pDeletePort, pVerifyAddress, pSendMessage, pGetFragment, pCancelTransaction, pUpdateReceiveInfo, pFinish, and pService

Service handler entries for the specified service. These must be initialized by putting a reference to each handler in the appropriate field. For handlers not implemented, the appropriate field is set to NULL.

Service handlers that correspond to these fields include:

`pInitialize`	Initialize
`pGetAttributes`	GetAttributes
`pSetAttributes`	SetAttributes
`pCreatePort`	CreatePort
`pDeletePort`	DeletePort
`pVerifyAddress`	VerifyAddress
`pSendMessage`	SendMessage
`pGetFragment`	GetFragment
`pCancelTransaction`	CancelTransaction
`pUpdateReceiveInfo`	UpdateReceiveInfo
`pFinish`	Finish
`pService`	Service

dwServiceThreadStackSize

Determines the size of the stack allocated to the service thread when it is created.

hServiceObject

The handle for the service object.

LocalAddress

This field contains a GENADDR structure to hold the address of the service interface. This field is relevant only to addressed services (see the description of the flags field, FL_ADDRESSED bit, above). This address may be configured before installation, or by using a SetRtServiceAttributes call.

wExtraSize

The number of bytes of data specific to this service appended to this structure.

Syntax

Fields

See Also