Структура LINEDEVCAPS (tapi.h)

Статья
03/08/2023

Структура LINEDEVCAPS описывает возможности линейного устройства. Функция lineGetDevCaps и функция TSPI_lineGetDevCaps возвращают структуру LINEDEVCAPS .

Синтаксис

typedef struct linedevcaps_tag {
  DWORD          dwTotalSize;
  DWORD          dwNeededSize;
  DWORD          dwUsedSize;
  DWORD          dwProviderInfoSize;
  DWORD          dwProviderInfoOffset;
  DWORD          dwSwitchInfoSize;
  DWORD          dwSwitchInfoOffset;
  DWORD          dwPermanentLineID;
  DWORD          dwLineNameSize;
  DWORD          dwLineNameOffset;
  DWORD          dwStringFormat;
  DWORD          dwAddressModes;
  DWORD          dwNumAddresses;
  DWORD          dwBearerModes;
  DWORD          dwMaxRate;
  DWORD          dwMediaModes;
  DWORD          dwGenerateToneModes;
  DWORD          dwGenerateToneMaxNumFreq;
  DWORD          dwGenerateDigitModes;
  DWORD          dwMonitorToneMaxNumFreq;
  DWORD          dwMonitorToneMaxNumEntries;
  DWORD          dwMonitorDigitModes;
  DWORD          dwGatherDigitsMinTimeout;
  DWORD          dwGatherDigitsMaxTimeout;
  DWORD          dwMedCtlDigitMaxListSize;
  DWORD          dwMedCtlMediaMaxListSize;
  DWORD          dwMedCtlToneMaxListSize;
  DWORD          dwMedCtlCallStateMaxListSize;
  DWORD          dwDevCapFlags;
  DWORD          dwMaxNumActiveCalls;
  DWORD          dwAnswerMode;
  DWORD          dwRingModes;
  DWORD          dwLineStates;
  DWORD          dwUUIAcceptSize;
  DWORD          dwUUIAnswerSize;
  DWORD          dwUUIMakeCallSize;
  DWORD          dwUUIDropSize;
  DWORD          dwUUISendUserUserInfoSize;
  DWORD          dwUUICallInfoSize;
  LINEDIALPARAMS MinDialParams;
  LINEDIALPARAMS MaxDialParams;
  LINEDIALPARAMS DefaultDialParams;
  DWORD          dwNumTerminals;
  DWORD          dwTerminalCapsSize;
  DWORD          dwTerminalCapsOffset;
  DWORD          dwTerminalTextEntrySize;
  DWORD          dwTerminalTextSize;
  DWORD          dwTerminalTextOffset;
  DWORD          dwDevSpecificSize;
  DWORD          dwDevSpecificOffset;
  DWORD          dwLineFeatures;
  DWORD          dwSettableDevStatus;
  DWORD          dwDeviceClassesSize;
  DWORD          dwDeviceClassesOffset;
  GUID           PermanentLineGuid;
  DWORD          dwAddressTypes;
  GUID           ProtocolGuid;
  DWORD          dwAvailableTracking;
} LINEDEVCAPS, *LPLINEDEVCAPS;

Члены

dwTotalSize

Общий размер, выделенный для этой структуры данных, в байтах.

dwNeededSize

Размер, необходимый для хранения всей возвращаемой информации в байтах в этой структуре данных.

dwUsedSize

Размер части этой структуры данных, содержащей полезную информацию, в байтах.

dwProviderInfoSize

Размер поля с изменяющимся размером, содержащего сведения о поставщике услуг, в байтах.

dwProviderInfoOffset

Смещение от начала структуры к сведениям о поставщике услуг в байтах.

Члены dwProviderInfoSize и dwProviderInfoOffset предназначены для предоставления сведений об оборудовании и программном обеспечении поставщика, таких как имя поставщика и номера версий оборудования и программного обеспечения. Эти сведения могут быть полезны, если пользователю необходимо обратиться в службу поддержки клиентов с проблемами, связанными с поставщиком.

dwSwitchInfoSize

Размер поля устройства изменяющегося размера, содержащего сведения о коммутаторе, в байтах.

dwSwitchInfoOffset

Смещение от начала структуры к сведениям о коммутаторе в байтах.

Члены dwSwitchInfoSize и dwSwitchInfoOffset предназначены для предоставления сведений о коммутаторе, к которому подключено устройство линии, например изготовителя коммутатора, имени модели, версии программного обеспечения и т. д. Эти сведения могут быть полезны, если пользователю необходимо вызвать службу поддержки клиентов с проблемами, связанными с коммутатором.

dwPermanentLineID

Постоянный идентификатор, по которому устройство линии известно в конфигурации системы. Это постоянное имя устройства линии. Это постоянное имя (в отличие от dwDeviceID) не изменяется при добавлении или удалении строк из системы и сохраняется в процессе обновления операционной системы. Поэтому его можно использовать для связывания сведений, относящихся к строкам, в файлах .ini (или других файлах) таким образом, который не затрагивается добавлением или удалением других строк или изменением операционной системы.

dwLineNameSize

Размер поля устройства изменяющегося размера, содержащего настраиваемое пользователем имя для этого устройства строки, в байтах.

dwLineNameOffset

Смещение от начала этой структуры данных до имени этого устройства линии. Это имя может быть настроено пользователем при настройке поставщика услуг устройства линии и предоставляется для удобства пользователя. Размер поля определяется параметром dwLineNameSize.

dwStringFormat

Формат строки, используемый с этим устройством линии. Этот элемент использует одну из констант STRINGFORMAT_.

dwAddressModes

Режим, в котором указывается исходный адрес. Этот элемент использует константы LINEADDRESSMODE_.

dwNumAddresses

Число адресов, связанных с этим устройством линии. На отдельные адреса ссылаются идентификаторы адресов. Диапазон идентификаторов адресов — от нуля до одного меньше значения, указанного dwNumAddresses.

dwBearerModes

Массив флагов, указывающий различные режимы носителя, которые поддерживает адрес. Этот элемент использует одну или несколько констант LINEBEARERMODE_.

dwMaxRate

Максимальная скорость передачи данных для обмена информацией по вызову в битах в секунду.

dwMediaModes

Массив флагов, указывающий различные типы носителей, которые поддерживает адрес. Этот элемент использует одну или несколько констант LINEMEDIAMODE_.

dwGenerateToneModes

Тоны, которые могут быть созданы в этой строке. Этот элемент использует одну или несколько констант LINETONEMODE_.

dwGenerateToneMaxNumFreq

Максимальное количество частот, которое можно указать при описании общего тона с помощью структуры данных LINEGENERATETONE при создании тона с помощью lineGenerateTone. Значение 0 указывает, что создание тона недоступно.

dwGenerateDigitModes

Режимы цифр, которые могут быть созданы в этой строке. Этот элемент использует одну или несколько констант LINEDIGITMODE_.

dwMonitorToneMaxNumFreq

Максимальное количество частот, которое можно указать при описании общего тона с помощью структуры данных LINEMONITORTONE при мониторинге общего тона с помощью lineMonitorTones. Значение 0 указывает, что монитор тона недоступен.

dwMonitorToneMaxNumEntries

Максимальное количество записей, которые можно указать в списке тональности lineMonitorTones.

dwMonitorDigitModes

Режимы цифр, которые можно определить в этой строке. Этот элемент использует одну или несколько констант LINEDIGITMODE_.

dwGatherDigitsMinTimeout

Минимальное значение, которое можно указать как для первой цифры, так и для межзначных значений времени ожидания, используемых lineGatherDigits, в миллисекундах. Если значения dwGatherDigitsMinTimeout и dwGatherDigitsMaxTimeout равны нулю, время ожидания не поддерживается.

dwGatherDigitsMaxTimeout

Максимальное значение, которое можно указать как для первой цифры, так и для значений времени ожидания между цифрами, используемых lineGatherDigits, в миллисекундах. Если значения dwGatherDigitsMinTimeout и dwGatherDigitsMaxTimeout равны нулю, время ожидания не поддерживается.

dwMedCtlDigitMaxListSize

Максимальное количество записей, которые можно указать в параметре списка цифр lineSetMediaControl.

dwMedCtlMediaMaxListSize

Максимальное количество записей, которое можно указать в параметре списка носителей объекта lineSetMediaControl.

dwMedCtlToneMaxListSize

Максимальное количество записей, которые можно указать в параметре списка тональности lineSetMediaControl.

dwMedCtlCallStateMaxListSize

Максимальное количество записей, которые можно указать в параметре списка состояний вызовов объекта lineSetMediaControl.

dwDevCapFlags

Возможности логического устройства. Этот элемент использует одну или несколько констант LINEDEVCAPFLAGS_.

dwMaxNumActiveCalls

Максимальное количество вызовов (минимальная пропускная способность), которые могут быть активными (подключенными) на линии в любой момент времени. Фактическое количество активных вызовов может быть меньше, если на линии установлено более высокое значение пропускной способности.

dwAnswerMode

Влияние на активный звонок при ответе на другой звонок предложения на устройстве линии. Этот элемент использует одну из констант LINEANSWERMODE_.

dwRingModes

Количество различных режимов кругов, которые можно сообщить в сообщении LINE_LINEDEVSTATE с указанием звонка . Различные режимы кругов варьируются от одного до dwRingModes. Ноль означает отсутствие кольца.

dwLineStates

Различные компоненты состояния строки, для которых приложение может получать уведомления в LINE_LINEDEVSTATE сообщении в этой строке. Этот элемент использует одну или несколько констант LINEDEVSTATE_.

dwUUIAcceptSize

Максимальный размер сведений о пользователе, включая признак конца null , которые могут быть отправлены во время приема вызова.

dwUUIAnswerSize

Максимальный размер сведений о пользователе, включая признак конца null , которые могут быть отправлены во время ответа на звонок.

dwUUIMakeCallSize

Максимальный размер сведений о пользователе, включая признак конца null , которые могут быть отправлены во время вызова.

dwUUIDropSize

Максимальный размер сведений пользователя и пользователя, включая признак конца null , которые могут быть отправлены во время удаления вызова.

dwUUISendUserUserInfoSize

Максимальный размер сведений о пользователе, включая признак конца NULL , которые могут быть отправлены отдельно в любое время во время вызова с помощью lineSendUserUserInfo.

dwUUICallInfoSize

Максимальный размер сведений о пользователе, включая признак конца null , который можно получить в структуре LINECALLINFO .

MinDialParams

Минимальное значение для параметров набора номера, которые можно задать для вызовов в этой строке, в миллисекундах. Для параметров набора номера можно задать значения в диапазоне MinDialParams в значение MaxDialParams. Степень детализации фактических параметров зависит от поставщика услуг.

MaxDialParams

Максимальное значение для параметров набора, которые можно задать для вызовов в этой строке, в миллисекундах. Для параметров набора номера можно задать значения в диапазоне MinDialParams в значение MaxDialParams. Степень детализации фактических параметров зависит от поставщика услуг.

DefaultDialParams

Параметры набора по умолчанию, используемые для вызовов в этой строке. Эти значения параметров можно переопределить по каждому вызову.

dwNumTerminals

Количество терминалов, которые можно задать для этого устройства линии, его адресов или вызовов. На отдельные терминалы ссылаются идентификаторы терминалов и они находятся в диапазоне от нуля до одного меньше значения, указанного в dwNumTerminals.

dwTerminalCapsSize

Размер поля устройства изменяющегося размера, содержащего массив с записями типа LINETERMCAPS, в байтах.

dwTerminalCapsOffset

Смещение от начала этой структуры до поля устройства изменяющегося размера, содержащего массив с записями типа LINETERMCAPS. Этот массив индексируется по идентификаторам терминалов в диапазоне от нуля до dwNumTerminals минус один. Каждая запись в массиве указывает возможности устройства терминала соответствующего терминала. Размер поля определяется dwTerminalCapsSize.

dwTerminalTextEntrySize

Размер каждого описания текста терминала, включая признак конца null , на который указывают dwTerminalTextSize и dwTerminalTextOffset, в байтах.

dwTerminalTextSize

Размер поля изменяющегося размера, содержащего описательный текст о каждом доступном терминале строки, включая признак конца null , в байтах

dwTerminalTextOffset

Смещение от начала этой структуры до описательного текста о каждом доступном терминале строки в байтах. Каждое сообщение имеет длину dwTerminalTextEntrySize в байтах. Строковый формат этих текстовых описаний обозначается dwStringFormat в возможностях устройства строки. Размер поля определяется параметром dwTerminalTextSize.

dwDevSpecificSize

Размер поля устройства с изменяемого размера в байтах. Если сведения, относящиеся к устройству, являются указателем на строку, размер должен включать признак конца null .

dwDevSpecificOffset

Смещение от начала этой структуры до поля устройства в байтах. Размер поля определяется dwDevSpecificSize.

dwLineFeatures

Функции, доступные для этой строки с помощью констант LINEFEATURE_. Для вызова поддерживаемой функции требуется, чтобы строка была в правильном состоянии, а базовое устройство линии было открыто в совместимом режиме. Ноль в битовом положении указывает, что соответствующая функция никогда не доступна. Один указывает, что соответствующая функция может быть доступна, если строка находится в соответствующем состоянии, чтобы операция была осмысленной. Этот член позволяет приложению определить, какие функции строки могут поддерживаться устройством (а какие никогда не поддерживаются).

dwSettableDevStatus

ЗНАЧЕНИЯ LINEDEVSTATUSFLAGS , которые можно изменить с помощью lineSetLineDevStatus.

dwDeviceClassesSize

Размер строки, содержащей идентификаторы класса устройства, поддерживаемые для одного или нескольких адресов в этой строке, включая признак конца null , в байтах.

dwDeviceClassesOffset

Смещение от начала этой структуры к строке, содержащей идентификаторы классов устройств, поддерживаемые для одного или нескольких адресов в этой строке, в байтах. Эти строки предназначены для использования с lineGetID; Они разделяются значениями NULL, а за последним идентификатором в списке следуют два значения NULL. Размер поля определяется dwDeviceClassesSize.

PermanentLineGuid

ИДЕНТИФИКАТОР GUID, постоянно связанный с устройством линии.

dwAddressTypes

Тип адреса , используемый для вызова. Этот элемент структуры доступен только в том случае, если согласованная версия TAPI — 3.0 или более поздняя.

ProtocolGuid

Текущий протокол TAPI. Этот элемент структуры доступен только в том случае, если согласованная версия TAPI — 3.0 или более поздняя. Протоколы объявляются в файле tapi3.h.

dwAvailableTracking

Доступное отслеживание, представленное LINECALLHUBTRACKING.constant. Этот элемент структуры доступен только в том случае, если согласованная версия TAPI — 3.0 или более поздняя.

Старые приложения компилируются без новых элементов в структуре LINEDEVCAPS и используют SIZEOF LINEDEVCAPS меньше нового размера. Приложение передает параметр dwAPIVersion с функцией lineGetDevCaps , которая может использоваться для указания TAPI при обработке этой ситуации. Если приложение передает член dwTotalSize меньше размера фиксированной части структуры, определенной в указанной dwAPIVersion, возвращается LINEERR_STRUCTURETOOSMALL. Если приложение выделило достаточно памяти, перед вызовом TSPI_lineGetDevCaps TAPI устанавливает для членов dwNeedededSize и dwUsedSize фиксированный размер структуры в том виде, в котором она существовала в указанной версии API.

Новые приложения должны учитывать согласованную версию API и не проверять содержимое элементов в фиксированной части за пределами исходной части фиксированной части структуры для согласованной версии API.

Если бит LINEBEARERMODE_DATA задан в элементе dwBearerModes , то элемент dwMaxRate указывает максимальную скорость цифровой передачи по каналу носителя. Элемент dwMaxRate структуры LINEDEVCAPS может содержать допустимые значения, даже если для элемента dwBearerModes структуры LINEDEVCAPS не задано значение LINEBEARERMODE_DATA.

Если LINEBEARERMODE_DATA не задано в dwBearerModes, но задано значение LINEBEARERMODE_VOICE и значение LINEMEDIAMODE_DATAMODEM задано в элементе dwMediaModes , то элемент dwMaxRate указывает максимальную скорость передачи данных SYNCHRONOUS (DCE) в телефонной линии для подключенного модема или функционального эквивалента. Например, если самая быстрая скорость модуляции модема составляет V.32bis со скоростью 14400 ббит/с, dwMaxRate равно 14400. Это не самая быстрая скорость портов DTE (скорее всего, 38400, 57600 или 115200), но самая быстрая скорость передачи, которую модем поддерживает на телефонной линии.

Приложение должно быть осторожным проверка, чтобы убедиться, что LINEBEARERMODE_DATA не задан, чтобы избежать неправильного толкования элемента dwMaxRate. Если задано значение LINEBEARERMODE_DATA, скорее всего, будет 64000 или выше.

Следует также отметить, что если модем не был специально идентифицирован (например, это "универсальный" модем), указанная цифра является "лучшей догадкой" на основе изучения модема.

Члены dwSettableDevStatus через dwDeviceClassesOffset доступны только для приложений, которые открывают устройство линии с TAPI версии 2.0 или более поздней.