6.1 Data Types

This chapter describes error codes, constants, data types, and structures used by the Telephony API. They are listed in alphabetical order.

For each data type or structure, this chapter lists the following items:

The purpose of the data type or structure

A description of the values or fields

A description of the type or structure's extensibility

Optional comments about using the data type or structure

Optional references to other functions, messages, and data types or structures.

Memory for all data structures used by the API is allocated by the application. The application passes a far pointer to the API function that returns the information. The API fills the data structure with the requested information. If the operation is asynchonous, then the information is not available until the asynchonous reply message indicates success.

All data structures used to pass information between the application and the Telephony API are flattened. This means that data structures do not contain pointers to substructures that contain variable size components of information. Instead, data structures with such variable sized parts are dealt with as follows.

Data structures used to pass variable amounts of information back to the application have the following meta structure:

DWORD dwTotalSize;

DWORD dwNeededSize;

DWORD dwUsedSize;

<fixed size fields>

DWORD dw<VarSizeField1>Size;

DWORD dw<VarSizeField1>Offset;

<fixed size fields>

DWORD dw<VarSizeField2>Size;

DWORD dw<VarSizeField2>Offset;

<common extensions>

<var sized field1>

<var sized field2>

The dwTotalSize field is the size in bytes allocated to this data structure, it marks the end of the data structure and is set by the application before it invokes the API function that uses this data structure. The API will not read or write beyond this size.

The dwNeededSize field is filled in by the API. It indicates how many bytes are needed to return all the information requested. The existence of variable size fields makes it often impossible for the application to a priori estimate the data structure size it needs to allocate. This field simply returns the number of bytes really needed for the infomation. This number could be smaller, equal, or larger than dwTotalSize, and includes the space for the dwTotalSize field itself. If larger, then the returned structure will only be partially filled. If the information fields the app is interest in are available in the partial structure, then nothing else need to be done. Otherwise, the app should allocate a structure of size at least dwNeededSize and invoke the operation again. Usually, enough space will be available this time to return all the information, although it is possible the size could have increased again.

The dwUsedSize field is filled in by the API if it returns information to the application to indicate the actual size in bytes of the data structure that contains useful information. If, for example, a structure was allocated too small and the truncated field is a variable size field, then dwNeededSize will be larger than dwTotalSize, and the truncated field will be left empty. dwUsedSize could therefore be smaller than dwTotalSize. Partial field values are not returned.

Following this header is the fixed part of the data structure. It contains regular fields and size/offset pairs that describe the actual variable sized fields. The offset field contains the offset in bytes of the variable sized field from the beginning of the record. The size field contains the size in bytes of the variable sized field. If a variable sized field is empty, then the size field is zero and the offset is set to zero. Variable sized field that would be truncated if the total structure size is insufficient, are left empty. I.e., their size field is set to zero and the offset is set to zero. The variable sized fields follow the fixed fields.