Estrutura LINEDEVCAPS (tapi.h)

Artigo
03/02/2024

A estrutura LINEDEVCAPS descreve os recursos de um dispositivo de linha. A função lineGetDevCaps e a função TSPI_lineGetDevCaps retornam a estrutura LINEDEVCAPS .

Sintaxe

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;

Membros

dwTotalSize

Tamanho total alocado para essa estrutura de dados, em bytes.

dwNeededSize

Tamanho necessário para que essa estrutura de dados mantenha todas as informações retornadas, em bytes.

dwUsedSize

Tamanho da parte dessa estrutura de dados que contém informações úteis, em bytes.

dwProviderInfoSize

Tamanho do campo de tamanho variavelmente que contém informações do provedor de serviços, em bytes.

dwProviderInfoOffset

Deslocamento do início da estrutura para as informações do provedor de serviços, em bytes.

Os membros dwProviderInfoSize e dwProviderInfoOffset destinam-se a fornecer informações sobre o hardware e/ou software do provedor, como o nome do fornecedor e os números de versão de hardware e software. Essas informações podem ser úteis quando um usuário precisa chamar o atendimento ao cliente com problemas relacionados ao provedor.

dwSwitchInfoSize

Tamanho do campo de dispositivo de tamanho variante que contém informações do comutador, em bytes.

dwSwitchInfoOffset

Deslocamento do início da estrutura para as informações de comutador, em bytes.

Os membros dwSwitchInfoSize e dwSwitchInfoOffset destinam-se a fornecer informações sobre a opção à qual o dispositivo de linha está conectado, como o fabricante do comutador, o nome do modelo, a versão do software e assim por diante. Essas informações podem ser úteis quando um usuário precisa chamar o atendimento ao cliente com problemas relacionados à opção.

dwPermanentLineID

Identificador permanente pelo qual o dispositivo de linha é conhecido na configuração do sistema. É um nome permanente para o dispositivo de linha. Esse nome permanente (em vez de dwDeviceID) não é alterado à medida que as linhas são adicionadas ou removidas do sistema e persiste por meio de atualizações do sistema operacional. Portanto, ele pode ser usado para vincular informações específicas de linha em arquivos de .ini (ou outros arquivos) de uma forma que não seja afetada pela adição ou remoção de outras linhas ou pela alteração do sistema operacional.

dwLineNameSize

Tamanho do campo de dispositivo de tamanho variativo que contém um nome configurável pelo usuário para este dispositivo de linha, em bytes.

dwLineNameOffset

Deslocamento do início dessa estrutura de dados para o nome deste dispositivo de linha. Esse nome pode ser configurado pelo usuário ao configurar o provedor de serviços do dispositivo de linha e é fornecido para a conveniência do usuário. O tamanho do campo é especificado por dwLineNameSize.

dwStringFormat

Formato de cadeia de caracteres usado com este dispositivo de linha. Esse membro usa uma das constantes STRINGFORMAT_.

dwAddressModes

Modo pelo qual o endereço de origem é especificado. Esse membro usa as constantes LINEADDRESSMODE_.

dwNumAddresses

Número de endereços associados a este dispositivo de linha. Endereços individuais são referenciados por identificadores de endereço. Os identificadores de endereço variam de zero a um a menos do que o valor indicado por dwNumAddresses.

dwBearerModes

Matriz de sinalizadores que indica os diferentes modos de portador aos quais o endereço é capaz de dar suporte. Esse membro usa uma ou mais das constantes LINEBEARERMODE_.

dwMaxRate

Taxa máxima de dados para troca de informações sobre a chamada, em bits por segundo.

dwMediaModes

Matriz de sinalizadores que indica os diferentes tipos de mídia aos quais o endereço é capaz de dar suporte. Esse membro usa uma ou mais das constantes LINEMEDIAMODE_.

dwGenerateToneModes

Tons que podem ser gerados nessa linha. Esse membro usa uma ou mais das constantes LINETONEMODE_.

dwGenerateToneMaxNumFreq

Número máximo de frequências que podem ser especificadas ao descrever um tom geral usando a estrutura de dados LINEGENERATETONE ao gerar um tom usando lineGenerateTone. Um valor 0 indica que a geração de tom não está disponível.

dwGenerateDigitModes

Modos de dígito que podem ser gerados nessa linha. Esse membro usa uma ou mais das constantes LINEDIGITMODE_.

dwMonitorToneMaxNumFreq

Número máximo de frequências que podem ser especificadas ao descrever um tom geral usando a estrutura de dados LINEMONITORTONE ao monitorar um tom geral usando lineMonitorTones. Um valor 0 indica que o monitor de tom não está disponível.

dwMonitorToneMaxNumEntries

Número máximo de entradas que podem ser especificadas em uma lista de tons para lineMonitorTones.

dwMonitorDigitModes

Modos de dígito que podem ser detectados nessa linha. Esse membro usa uma ou mais das constantes LINEDIGITMODE_.

dwGatherDigitsMinTimeout

Valor mínimo que pode ser especificado para os valores de tempo limite de primeiro dígito e entre dígitos usados por lineGatherDigits, em milissegundos. Se dwGatherDigitsMinTimeout e dwGatherDigitsMaxTimeout forem zero, não há suporte para tempos limite.

dwGatherDigitsMaxTimeout

Valor máximo que pode ser especificado para os valores de tempo limite de primeiro dígito e entre dígitos usados por lineGatherDigits, em milissegundos. Se dwGatherDigitsMinTimeout e dwGatherDigitsMaxTimeout forem zero, não há suporte para tempos limite.

dwMedCtlDigitMaxListSize

Número máximo de entradas que podem ser especificadas no parâmetro de lista de dígitos de lineSetMediaControl.

dwMedCtlMediaMaxListSize

Número máximo de entradas que podem ser especificadas no parâmetro de lista de mídia de lineSetMediaControl.

dwMedCtlToneMaxListSize

Número máximo de entradas que podem ser especificadas no parâmetro de lista de tons de lineSetMediaControl.

dwMedCtlCallStateMaxListSize

Número máximo de entradas que podem ser especificadas no parâmetro de lista de estado de chamada de lineSetMediaControl.

dwDevCapFlags

Funcionalidades do dispositivo booliano. Esse membro usa uma ou mais das constantes LINEDEVCAPFLAGS_.

dwMaxNumActiveCalls

Número máximo de chamadas (largura de banda mínima) que podem estar ativas (conectadas) na linha a qualquer momento. O número real de chamadas ativas poderá ser menor se chamadas de largura de banda mais altas tiverem sido estabelecidas na linha.

dwAnswerMode

Efeito na chamada ativa ao atender outra chamada de oferta em um dispositivo de linha. Esse membro usa uma das constantes LINEANSWERMODE_.

dwRingModes

Número de modos de anel diferentes que podem ser relatados na mensagem LINE_LINEDEVSTATE com a indicação de toque . Diferentes modos de anel variam de um a dwRingModes. Zero indica nenhum anel.

dwLineStates

Diferentes componentes de status de linha para os quais o aplicativo pode ser notificado em uma mensagem LINE_LINEDEVSTATE nessa linha. Esse membro usa uma ou mais das constantes LINEDEVSTATE_.

dwUUIAcceptSize

Tamanho máximo de informações do usuário-usuário, incluindo o terminador nulo , que podem ser enviadas durante uma aceitação de chamada.

dwUUIAnswerSize

Tamanho máximo de informações do usuário-usuário, incluindo o terminador nulo , que podem ser enviadas durante uma resposta de chamada.

dwUUIMakeCallSize

Tamanho máximo de informações do usuário-usuário, incluindo o terminador nulo , que podem ser enviadas durante uma chamada de make.

dwUUIDropSize

Tamanho máximo de informações do usuário-usuário, incluindo o terminador nulo , que podem ser enviadas durante uma queda de chamada.

dwUUISendUserUserInfoSize

Tamanho máximo de informações de usuário-usuário, incluindo o terminador nulo , que podem ser enviadas separadamente a qualquer momento durante uma chamada com lineSendUserUserInfo.

dwUUICallInfoSize

Tamanho máximo de informações de usuário-usuário, incluindo o terminador nulo , que podem ser recebidas na estrutura LINECALLINFO .

MinDialParams

Valor mínimo para os parâmetros de discagem que podem ser definidos para chamadas nessa linha, em milissegundos. Os parâmetros de discagem podem ser definidos como valores no intervalo MinDialParams como MaxDialParams. A granularidade das configurações reais é específica do provedor de serviços.

MaxDialParams

Valor máximo para os parâmetros de discagem que podem ser definidos para chamadas nessa linha, em milissegundos. Os parâmetros de discagem podem ser definidos como valores no intervalo MinDialParams como MaxDialParams. A granularidade das configurações reais é específica do provedor de serviços.

DefaultDialParams

Parâmetros de discagem padrão usados para chamadas nessa linha. Esses valores de parâmetro podem ser substituídos por chamada.

dwNumTerminals

Número de terminais que podem ser definidos para esse dispositivo de linha, seus endereços ou suas chamadas. Os terminais individuais são referenciados por IDs de terminal e variam de zero a um a menos do que o valor indicado por dwNumTerminals.

dwTerminalCapsSize

Tamanho do campo de dispositivo de tamanho variável que contém uma matriz com entradas do tipo LINETERMCAPS, em bytes.

dwTerminalCapsOffset

Deslocamento do início dessa estrutura para o campo de dispositivo de tamanho variável que contém uma matriz com entradas do tipo LINETERMCAPS. Essa matriz é indexada por IDs de terminal, no intervalo de zero a dwNumTerminals menos um. Cada entrada na matriz especifica os recursos de dispositivo de terminal do terminal correspondente. O tamanho do campo é especificado por dwTerminalCapsSize.

dwTerminalTextEntrySize

Tamanho de cada uma das descrições de texto do terminal, incluindo o terminador nulo , apontado por dwTerminalTextSize e dwTerminalTextOffset, em bytes.

dwTerminalTextSize

Tamanho do campo de tamanho variativo que contém texto descritivo sobre cada um dos terminais disponíveis da linha, incluindo o terminador nulo , em bytes

dwTerminalTextOffset

Deslocamento do início dessa estrutura para o texto descritivo sobre cada um dos terminais disponíveis da linha, em bytes. Cada mensagem é dwTerminalTextEntrySize bytes long. O formato de cadeia de caracteres dessas descrições textuais é indicado por dwStringFormat nas funcionalidades do dispositivo da linha. O tamanho do campo é especificado por dwTerminalTextSize.

dwDevSpecificSize

Tamanho do campo específico do dispositivo de tamanho variavelmente, em bytes. Se as informações específicas do dispositivo forem um ponteiro para uma cadeia de caracteres, o tamanho deverá incluir o terminador nulo .

dwDevSpecificOffset

Deslocamento do início dessa estrutura para o campo específico do dispositivo, em bytes. O tamanho do campo é especificado por dwDevSpecificSize.

dwLineFeatures

Recursos disponíveis para essa linha usando as constantes LINEFEATURE_. Invocar um recurso com suporte requer que a linha esteja no estado adequado e que o dispositivo de linha subjacente seja aberto em um modo compatível. Um zero em uma posição de bit indica que o recurso correspondente nunca está disponível. Um indica que o recurso correspondente poderá estar disponível se a linha estiver no estado apropriado para que a operação seja significativa. Esse membro permite que um aplicativo descubra quais recursos de linha podem ser (e quais nunca podem ser) compatíveis com o dispositivo.

dwSettableDevStatus

Valores LINEDEVSTATUSFLAGS que podem ser modificados usando lineSetLineDevStatus.

dwDeviceClassesSize

Tamanho de uma cadeia de caracteres que contém os identificadores de classe de dispositivo com suporte em um ou mais endereços nessa linha, incluindo o terminador nulo , em bytes.

dwDeviceClassesOffset

Deslocamento do início dessa estrutura para uma cadeia de caracteres que contém os identificadores de classe de dispositivo com suporte em um ou mais endereços nessa linha, em bytes. Essas cadeias de caracteres são usadas com lineGetID; eles são separados por NULLe o último identificador na lista é seguido por dois NULLs. O tamanho do campo é especificado por dwDeviceClassesSize.

PermanentLineGuid

GUID permanentemente associado ao dispositivo de linha.

dwAddressTypes

Tipo de endereço usado para a chamada. Esse membro da estrutura só estará disponível se a versão da TAPI negociada for 3.0 ou superior.

ProtocolGuid

Protocolo TAPI atual. Esse membro da estrutura só estará disponível se a versão da TAPI negociada for 3.0 ou superior. Os protocolos são declarados em tapi3.h.

dwAvailableTracking

Acompanhamento disponível, conforme representado por um LINECALLHUBTRACKING.constant. Esse membro da estrutura só estará disponível se a versão da TAPI negociada for 3.0 ou superior.

Comentários

As extensões específicas do dispositivo devem usar a área de tamanho variável DevSpecific (dwDevSpecificSize e dwDevSpecificOffset) dessa estrutura de dados.

Aplicativos mais antigos são compilados sem novos membros na estrutura LINEDEVCAPS e usando um SIZEOF LINEDEVCAPS menor que o novo tamanho. O aplicativo passa um parâmetro dwAPIVersion com a função lineGetDevCaps , que pode ser usada para orientação do TAPI para lidar com essa situação. Se o aplicativo passar em um membro dwTotalSize menor que o tamanho da parte fixa da estrutura conforme definido no dwAPIVersion especificado, LINEERR_STRUCTURETOOSMALL será retornado. Se a memória suficiente tiver sido alocada pelo aplicativo, antes de chamar TSPI_lineGetDevCaps, TAPI definirá os membros dwNeedEdSize e dwUsedSize como o tamanho fixo da estrutura como ela existia na versão da API especificada.

Novos aplicativos devem estar cientes da versão da API negociada e não examinar o conteúdo dos membros na parte fixa além do final original da parte fixa da estrutura para a versão da API negociada.

Se o bit LINEBEARERMODE_DATA estiver definido no membro dwBearerModes , o membro dwMaxRate indicará a taxa máxima de transmissão digital no canal de portador. O membro dwMaxRate da estrutura LINEDEVCAPS pode conter valores válidos mesmo se o membro dwBearerModes da estrutura LINEDEVCAPS não estiver definido como LINEBEARERMODE_DATA.

Se LINEBEARERMODE_DATA não estiver definido em dwBearerModes, mas o valor LINEBEARERMODE_VOICE for definido e o valor LINEMEDIAMODE_DATAMODEM for definido no membro dwMediaModes , o membro dwMaxRate indicará a taxa máxima de bits SÍNCRONA (DCE) na linha do telefone para o modem anexado ou equivalente funcional. Por exemplo, se a velocidade de modulação mais rápida do modem for V.32bis a 14.400bps, dwMaxRate será igual a 14400. Essa não é a taxa de porta DTE mais rápida (que provavelmente seria 38400, 57600 ou 115200), mas a taxa de bits mais rápida que o modem dá suporte na linha telefônica.

O aplicativo deve ter cuidado para marcar para ver que LINEBEARERMODE_DATA não está definido, para evitar interpretar incorretamente o membro dwMaxRate. É provável que seja 64.000 ou superior se LINEBEARERMODE_DATA estiver definido.

Também deve ser observado que, se o modem não tiver sido identificado especificamente (por exemplo, é um modem "genérico"), a figura indicada será um "melhor palpite" com base no exame do modem.

Os membros dwSettableDevStatus por meio de dwDeviceClassesOffset estão disponíveis apenas para aplicativos que abrem o dispositivo de linha com uma versão TAPI de 2.0 ou posterior.