Função ConfigDriver

Conformidade
Versão introduzida: ODBC 2.5

Resumo
O ConfigDriver permite que um programa de instalação execute funções de instalação e desinstalação sem exigir que o programa chame ConfigDSN. Essa função executará funções específicas do driver, como criar informações do sistema específicas do driver e executar conversões de DSN durante a instalação, bem como limpar as modificações de informações do sistema durante a desinstalação. Essa função é exposta pela DLL de instalação do driver ou por uma DLL de instalação separada.

Sintaxe

  
BOOL ConfigDriver(  
      HWND    hwndParent,  
      WORD    fRequest,  
      LPCSTR  lpszDriver,  
      LPCSTR  lpszArgs,  
      LPSTR   lpszMsg,  
      WORD    cbMsgMax,  
      WORD *  pcbMsgOut);  

Argumentos

hwndParent
[Entrada] Identificador de janela pai. A função não exibirá nenhuma caixa de diálogo se o identificador for nulo.

fRequest
[Entrada] Tipo de solicitação. O argumento fRequest deve conter um dos seguintes valores:

ODBC_INSTALL_DRIVER: instalar um novo driver.

ODBC_REMOVE_DRIVER: remover um driver.

Essa opção também pode ser específica do driver, caso em que o argumento fRequest para a primeira opção deve começar de ODBC_CONFIG_DRIVER_MAX+1. O argumento fRequest para qualquer opção adicional também deve começar com um valor maior que ODBC_CONFIG_DRIVER_MAX+1.

lpszDriver
[Entrada] O nome do driver conforme registrado na chave Odbcinst.ini das informações do sistema.

lpszArgs
[Entrada] Uma cadeia de caracteres terminada em nulo que contém argumentos para um fRequest específico do driver.

lpszMsg
[Saída] Uma cadeia de caracteres terminada em nulo que contém uma mensagem de saída da configuração do driver.

cbMsgMax
[Entrada] Comprimento de lpszMsg.

pcbMsgOut
[Saída] Número total de bytes disponíveis para retornar em lpszMsg.

Se o número de bytes disponíveis para retornar for maior ou igual a cbMsgMax, a mensagem de saída em lpszMsg será truncada para cbMsgMax menos o caractere de terminação nula. O argumento pcbMsgOut pode ser um ponteiro nulo.

Retornos

A função retornará TRUE se for bem-sucedida, FALSE se falhar.

Diagnósticos

Quando ConfigDriver retorna FALSE, um valor *pfErrorCode associado é postado no buffer de erros do instalador por uma chamada para SQLPostInstallerError e pode ser obtido chamando SQLInstallerError. A tabela a seguir lista os valores *pfErrorCode que podem ser retornados por SQLInstallerError e explica cada um deles no contexto dessa função.

*pfErrorCode	Erro	Descrição
ODBC_ERROR_INVALID_HWND	Identificador de janela inválido	O argumento hwndParent era inválido.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo inválido de solicitação	O argumento fRequest não foi um dos seguintes: ODBC_INSTALL_DRIVER ODBC_REMOVE_DRIVER A opção específica do driver era menor ou igual a ODBC_CONFIG_DRIVER_MAX.
ODBC_ERROR_INVALID_NAME	Nome do driver ou tradutor inválido	O argumento lpszDriver era inválido. Não foi possível encontrá-lo no registro.
ODBC_ERROR_REQUEST_FAILED	Falha na solicitação	Não foi possível executar a operação solicitada pelo argumento fRequest .
ODBC_ERROR_DRIVER_SPECIFIC	Erro específico do driver ou do tradutor	Um erro específico do driver para o qual não há nenhum erro definido do instalador ODBC. O argumento SzError em uma chamada para a função SQLPostInstallerError deve conter a mensagem de erro específica do driver.

Comentários

Opções do Driver-Specific

Um aplicativo pode solicitar recursos específicos do driver expostos pelo driver usando o argumento fRequest . A fRequest para a primeira opção será ODBC_CONFIG_DRIVER_MAX mais 1 e opções adicionais serão incrementadas em 1 desse valor. Todos os argumentos exigidos pelo driver para essa função devem ser fornecidos em uma cadeia de caracteres terminada em nulo passada no argumento lpszArgs . Os drivers que fornecem essa funcionalidade devem manter uma tabela de opções específicas do driver. As opções devem estar totalmente documentadas na documentação do driver. Os gravadores de aplicativos que usam opções específicas do driver devem estar cientes de que isso tornará o aplicativo menos interoperável.

Mensagens

Uma rotina de configuração de driver pode enviar uma mensagem de texto para um aplicativo como uma cadeia de caracteres terminada em nulo no buffer lpszMsg . A mensagem será truncada para cbMsgMax menos o caractere de terminação nula pela função ConfigDriver se for maior ou igual a caracteres cbMsgMax .