Structures in TSPI

A service provider uses structures to receive and return the data associated with a telephony request. In many cases, the members in a structure vary in length or number depending on the context of the specific request.

The structures do not contain pointers.

DWORD  dwTotalSize;
    DWORD  dwNeededSize;
    DWORD  dwUsedSize;
       // fixed size fields
    DWORD  dwField1Size;
    DWORD  dwField1Offset;
       // fixed size fields
    DWORD  dwField2Size;
    DWORD  dwField2Offset;
       // common extensions
       // var sized field1
       // var sized field2
 

A structure consists of a fixed set of members, followed by zero or more variable members.

The first three fixed members specify the size of the structure. The dwTotalSize member, set by the application and verified by TAPI, specifies the total size in bytes of memory allocated for the structure. The dwNeededSize member specifies the total size in bytes needed for the data to be filled into the structure. The dwUsedSize member indicates the total size in bytes of the data that is actually filled in.

Each variable member has a pair of corresponding fixed members that specify the size and the offset, in bytes, from the beginning of the structure to the variable member.

Before passing a structure to the service provider, TAPI ensures that the memory for the structure is writable and that the value in dwTotalSize covers at least the fixed part of the structure. TAPI sets the dwUsedSize and the dwNeededSize members to the size of the fixed part.

If the service provider is responsible for filling in a variable member, TAPI sets the corresponding size and offset members to zero. If the service provider fills in the variable member, it must set the corresponding size and offset members to appropriate values. The service provider must not truncate a variable member to make it fit into the available space.

The service provider must:

• Set the fixed and variable members for which it is responsible.
• Update the dwUsedSize member if it sets variable members. This must be the size of all fixed members, plus the size of all variable members the service provider was able to copy to the available space.
• Update the dwNeededSize member if it has any variable members. This must be the size of all fixed members plus the size of all variable members, not just those copied to the available space.

The service provider must start variable members immediately after the fixed members of the structure, and leave any extra space at the end of the allocated memory so that TAPI can use it for the variable-length members for which it is responsible. It can place the variable members in any order, but the members must be contiguous.

If the service provider detects an error, it must return the appropriate error return; no members need to be filled in. Insufficient space for variable members is not an error. The service provider simply sets dwUsedSize and dwNeededSize as appropriate and returns SUCCESS. Unless an error occurs, the service provider must set all fixed members for which it is responsible.

TAPI sets the fixed and variable members that it is responsible for after the service provider.