内存分配

应用程序必须为此数据分配内存;TAPI 和服务提供商提供数据。 如果操作是异步的,则在异步答复消息指示成功之前,数据不可用。

用于在应用程序和 TAPI 之间传递数据的所有数据结构均 平展。 也就是说,数据结构不包含指向包含可变大小的数据组件的子结构的指针。 相反,用于将可变数据量传递回应用程序的数据结构必须具有以下元结构:

  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>

dwTotalSize 成员是分配给此数据结构的大小(以字节为单位)。 它标记数据结构的末尾,并由应用程序在调用使用此数据结构的函数之前设置。 此函数不会读取或写入超出此大小。 应用程序必须设置 dwTotalSize 成员,以指示为 TAPI 分配的总字节数以返回结构的内容。

TAPI 填充 dwNeededSize 成员。 它指示返回所有请求的数据所需的字节数。 存在可变大小的字段通常使得应用程序无法估计分配所需的数据结构大小。 此字段返回数据实际所需的字节数。 此数字可以小于、等于或大于 dwTotalSize,并且它包含 dwTotalSize 成员本身的空间。 如果较大,则返回的结构仅部分填充。 如果应用程序所需的字段在部分结构中可用,则无需执行其他任何操作。 否则,应用程序应至少分配 dwNeededSize 的大小结构,然后再次调用该函数。 通常,此时间有足够的空间来返回所有信息,尽管大小可能再次增加。

如果 TAPI 向应用程序返回数据以指示包含有用数据的数据结构部分的实际大小(以字节为单位)来填充 dwUsedSize 成员。 例如,如果分配的结构太小,截断字段是可变大小的字段, dwNeededSize 大于 dwTotalSize,并且截断的字段留空。 因此, dwUsedSize 成员可能小于 dwTotalSize。 不返回部分字段值。

遵循此标头是数据结构的固定部分。 它包含描述实际可变大小的字段的常规字段和大小/偏移量对。 偏移量字段包含从记录开头可变大小的字段的偏移量(以字节为单位)。 大小字段包含可变大小字段的大小(以字节为单位)。 如果可变大小字段为空,则大小字段为零,偏移量设置为零。 如果总结构大小不足,将截断的可变大小字段为空。 也就是说,其大小字段设置为零,偏移量设置为零。 固定大小的字段遵循固定字段。

如果服务提供商必须填充变量成员,TAPI 会将相应的大小和偏移成员初始化为零。 如果服务提供商填充变量成员,则必须将相应的大小和偏移成员设置为适当的值,包括 dwUsedSizedwNeededSize (如果它设置变量成员)。 服务提供商不得截断变量成员,使其适合可用空间。

服务提供商必须在结构的固定成员之后立即启动变量成员,并在分配的内存末尾留出任何额外的空间,以便 TAPI 可以将其用于可变长度成员。 它可以按任意顺序放置变量成员,但成员必须连续。