função TSPI_lineSetDevConfig (tspi.h)

Artigo
08/26/2023

A função TSPI_lineSetDevConfig restaura a configuração de um dispositivo associado um para um com o dispositivo de linha de uma estrutura de dados obtida anteriormente usando TSPI_lineGetDevConfig. O conteúdo dessa estrutura de dados é específico para a linha [provedor de serviços] e a classe de dispositivo.

Sintaxe

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

Parâmetros

dwDeviceID

O dispositivo de linha a ser configurado.

lpDeviceConfig

Um ponteiro para a estrutura de dados de configuração retornada na parte variável da estrutura VARSTRING por TSPI_lineGetDevConfig.

dwSize

O número de bytes na estrutura apontada por lpDeviceConfig. Esse valor é retornado no membro dwStringSize na estrutura VARSTRING retornada por TSPI_lineGetDevConfig.

Nota Se os parâmetros de tamanho na estrutura não estiverem corretos, há a possibilidade de que os dados possam ser substituídos. Para obter mais informações sobre como definir tamanhos de estrutura, consulte o tópico de alocação de memória .

lpszDeviceClass

Um ponteiro para uma cadeia de caracteres Unicode terminada em nulo que especifica a classe de dispositivo do dispositivo cuja configuração deve ser restaurada. 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" (ou seja, quando dwSelect tem o valor LINECALLSELECT_LINE).

Retornar valor

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:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL LINEERR_NODRIVER.

Comentários

O estado da chamada é específico do dispositivo.

O provedor de serviços retornará LINEERR_INVALPARAM se as informações contidas na estrutura apontada por lpDeviceConfig não forem válidas para este dispositivo.

O provedor de serviços retornará LINEERR_INVALLINESTATE se a configuração do dispositivo não puder ser alterada no estado de linha atual. A linha pode estar em uso por outro aplicativo.

Essa função pode ser usada para restaurar a configuração de um dispositivo associado um para um com o dispositivo de linha de uma estrutura de dados recuperada anteriormente do provedor de serviços usando a função TSPI_lineGetDevConfig . O parâmetro lpszDeviceClass seleciona qual das várias classes de dispositivos possivelmente diferentes deve ter sua configuração restaurada. 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 permite a classe de dispositivo tapi/line nessa função. Ele restaura parâmetros que têm escopo de "linha", como a lista de endereços nessa linha e a lista de dispositivos de hardware físico, como portas COMM correspondentes aos endereços ou o número máximo de chamadas simultâneas (se configurável).

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 é 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.

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 e chamadas múltiplas, apenas um subconjunto de provedores de serviços dá suporte a elas. Os programas de aplicativo provavelmente não adicionarão uma dependência específica do dispositivo na 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 o 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 da instância em vez do escopo da classe. A API de mídia de alto nível precisa 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, todas essas informações temporárias que foram definidas ou recuperadas por meio de TSPI_lineGetDevConfig podem reverter a 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 passada para essa função é específico para a API de linha e classe de dispositivo, não está documentado e é indefinido. A estrutura passada para essa função não pode ser acessada ou manipulada diretamente pelo aplicativo, mas só pode ser armazenada intacta e posteriormente usada de um TSPI_lineGetDevConfig anterior para obter 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 marcar essa estrutura de dados para que a consistência se proteja contra falhas devido a um aplicativo cliente passando informações incompatíveis.

Nota Alguns provedores de serviços podem permitir que a configuração seja definida enquanto um dispositivo está em uso e outros não.