função TSPI_lineGetDevConfig (tspi.h)

Artigo
08/26/2023

A função TSPI_lineGetDevConfig retorna um objeto de estrutura de dados, cujo conteúdo é específico para a linha (provedor de serviços) e a classe de dispositivo, dando a configuração atual de um dispositivo associado um para um com o dispositivo de linha.

Sintaxe

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

Parâmetros

dwDeviceID

O dispositivo de linha a ser configurado.

lpDeviceConfig

Um ponteiro para uma estrutura de dados do tipo VARSTRING em que a estrutura de configuração do dispositivo associado é retornada. Após a conclusão bem-sucedida da solicitação, o provedor de serviços preenche essa estrutura de dados com a configuração do dispositivo. O membro dwStringFormat na estrutura VARSTRING deve ser definido como STRINGFORMAT_BINARY. Se o membro dwTotalSize da estrutura VARSTRING apontado pelo parâmetro lpDeviceConfig for maior ou igual ao tamanho da parte fixa da estrutura, o provedor de serviços definirá o membro dwNeededSize como o tamanho necessário e retornará zero.

lpszDeviceClass

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que especifica a classe de dispositivo do dispositivo cuja configuração é solicitada. As cadeias de caracteres de classe de dispositivo válidas são as mesmas especificadas para a função TSPI_lineGetID quando ela é aplicada a um dispositivo de linha (dwSelect tem o valor LINECALLSELECT_LINE).

Valor retornado

Retornará zero se a função for bem-sucedida ou um número de erro se ocorrer um erro. Os valores retornados possíveis são os seguintes:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Comentários

O estado da chamada é específico do dispositivo.

Essa função pode ser usada para recuperar uma estrutura de dados do provedor de serviços que especifica a configuração de um dispositivo associado um para um com o dispositivo de linha. O parâmetro lpszDeviceClass seleciona qual das várias classes de dispositivos possivelmente diferentes deve ter sua configuração recuperada. O conjunto de classes com suporte é restrito àqueles cujos dispositivos correspondem um para um com o dispositivo de linha. Para obter mais informações sobre classes de dispositivo comuns, consulte Classes de dispositivo TSPI.

Um provedor de serviços normalmente deve permitir a classe de dispositivo tapi/line nessa função. Ele recuperaria parâmetros que têm escopo de "linha", como a lista de endereços nessa linha, a lista de dispositivos de hardware físico, como portas COMM correspondentes aos endereços, número máximo de chamadas simultâneas (se configurável) e assim por diante.

Em geral, essa função não permite classes de dispositivo relacionadas à mídia, como mci waveaudio, onda de baixo nível ou classes de dispositivo datamodem, porque geralmente se aplicam a uma chamada específica ou a um endereço específico. Como pode haver mais de um desses dispositivos por linha, a identificação da chamada ou endereço específico simplesmente pelo parâmetro de identificador de dispositivo de linha nessa função seria ambígua. Uma exceção pode ser feita para classes de dispositivo específicas de chamada ou específicas de endereço nos casos em que há informações de configuração de classe que se aplicam a todo o escopo do dispositivo de linha, como padrões iniciais e assim por diante.

Há vários motivos pelos quais o suporte excepcional para classes de dispositivo específicas de chamada e específicas de endereço é de apenas um valor limitado nessa função. Primeiro, como essas classes podem ser ambíguas em provedores de serviços de vários endereços/várias chamadas, apenas um subconjunto de provedores de serviços dá suporte a elas. Não é provável que os aplicativos adicionem uma dependência específica do dispositivo à inclusão dessas classes nessa função. Em segundo lugar, à medida que surgem "classes" de mídia de nível superior que implementam protocolos de alto nível, como acesso ao sistema de arquivos de discagem em termos de APIs de transporte de baixo nível, a configuração dessas classes tende ao escopo de "instância" em vez do escopo de "classe". A API de mídia de alto nível deve fornecer suas próprias funções para configurar instâncias específicas de chamada ou de endereço.

Qualquer que seja o tipo de dispositivo e classes de dispositivos compatíveis com essa função, ela pode afetar potencialmente dois tipos de informações de configuração: permanentes e temporárias. As informações permanentes sobrevivem em diferentes "aberturas" da linha e até mesmo em diferentes "inicializações" do próprio provedor de serviços. As informações temporárias só sobrevivem dentro de um "aberto" exclusivo da linha. Quando a linha é fechada, qualquer informação temporária que tenha sido recuperada ou definida por meio de TSPI_lineSetDevConfig pode reverter para valores padrão ou indefinidos. O chamador pode recuperar de forma confiável qualquer configuração temporária apenas por uma sequência como TSPI_lineOpen, TSPI_lineConfigDialogTSPI_lineGetDevConfig. O chamador pode definir de forma confiável as informações de configuração temporárias recuperadas por essa sequência por meio de uma sequência como TSPI_lineOpenTSPI_lineSetDevConfig. A parte temporária da configuração permanece estável apenas até o próximo TSPI_lineConfigDialog, TSPI_lineSetDevConfig ou TSPI_lineClose. O provedor de serviços deve cuidar do armazenamento de qualquer parte permanente da configuração, normalmente em um arquivo .ini e recarregá-lo sempre que o provedor de serviços for inicializado.

O formato exato dos dados contidos na estrutura retornada por essa função é específico para a API de linha e classe de dispositivo, não está documentado e é indefinido. A estrutura retornada por essa função não pode ser acessada ou manipulada diretamente pelo aplicativo, mas só pode ser armazenada intacta e posteriormente usada em TSPI_lineSetDevConfig para restaurar as configurações. A estrutura também não pode necessariamente ser passada para outros dispositivos, mesmo da mesma classe de dispositivo (embora isso possa funcionar em alguns casos, não é garantido). Um provedor de serviços deve colocar itens na estrutura de dados para permitir que ele seja verificado quanto à consistência para se proteger contra falhas devido a um aplicativo cliente passando informações incompatíveis.