Função AddPortUI (winsplp.h)

Artigo
08/08/2023

Uma função AddPortUI da DLL de monitor de porta adiciona uma porta de impressora e, em seguida, obtém informações de configuração de porta do usuário e as envia para a DLL do servidor de monitor de porta.

Sintaxe

BOOL AddPortUI(
  [in, optional]  PCWSTR pszServer,
  [in]            HWND   hWnd,
                  PCWSTR pszMonitorNameIn,
  [out, optional] PWSTR  *ppszPortNameOut
);

Parâmetros

[in, optional] pszServer

Ponteiro fornecido pelo chamador para uma cadeia de caracteres que representa um nome de servidor ou NULL se a impressora for local.

[in] hWnd

Identificador fornecido pelo chamador da janela que deve ser usada como pai para caixas de diálogo. Se FOR NULL, nenhuma caixa de diálogo deverá ser exibida.

pszMonitorNameIn

Ponteiro fornecido pelo chamador para uma cadeia de caracteres que representa o nome do monitor. Pode ser NULL.

[out, optional] ppszPortNameOut

Ponteiro fornecido pelo chamador para um local para receber uma cadeia de caracteres de nome de porta. Pode ser NULL, caso em que um nome não é retornado.

Retornar valor

Se a operação for bem-sucedida, a função deverá retornar TRUE. Caso contrário, SetLastError deverá ser chamado para especificar um código de erro e a função deverá retornar FALSE. Se a operação for cancelada pelo usuário ou não tiver suporte, a função deverá chamar SetLastError(ERROR_CANCELLED) e retornar FALSE.

Comentários

As DLLs da interface do usuário do monitor de porta são necessárias para definir uma função AddPortUI e incluir o endereço da função em uma estrutura MONITORUI .

O spooler chama AddPortUI de dentro de sua função AddPort. Os três primeiros argumentos recebidos por AddPortUI são os argumentos recebidos pelo AddPort. (A função AddPort é descrita na documentação do SDK do Microsoft Windows.)

A função deve executar as seguintes operações:

Chame OpenPrinter, especificando um nome de impressora com o seguinte formato:

\\ServerName\,XcvMonitorMonitorName

em que ServerName e MonitorName são os nomes de servidor e monitor recebidos como argumentos de função AddPortUI .

A chamada para OpenPrinter requer uma estrutura PRINTER_DEFAULTS, que é descrita na documentação do SDK do Windows. O membro DesiredAccess da estrutura deve ser definido como SERVER_ACCESS_ADMINISTER. Seus membros pDatatype e pDevMode podem ser NULL.

Essa chamada faz com que a função XcvOpenPort do servidor de monitor de impressão seja chamada.
Obtenha um nome de porta do usuário exibindo uma caixa de diálogo.
Chame XcvData, especificando os seguintes argumentos de entrada:
- O identificador recebido do OpenPrinter
- O nome da porta recebido do usuário
- Uma cadeia de caracteres de nome de dados personalizada, como "PortExists"
Essa chamada faz com que a função XcvDataPort da DLL do servidor seja chamada. A função XcvDataPort deve retornar um valor que indique se o nome da porta especificado já foi usado. Se tiver, a DLL da interface do usuário deverá solicitar outro nome do usuário e chamar XcvData novamente.
Depois que um novo nome de porta válido tiver sido recebido, chame XcvData novamente, desta vez especificando os seguintes argumentos de entrada
- O identificador recebido do OpenPrinter
- O nome da porta validado recebido do usuário
- Uma cadeia de caracteres de nome de dados de "AddPort"
Essa chamada faz com que a função XcvDataPort da DLL do servidor seja chamada novamente.
Obtenha parâmetros de configuração de porta do usuário exibindo uma caixa de diálogo.
Chame XcvData uma ou mais vezes, especificando cadeias de caracteres de nome de dados personalizadas, para enviar cada parâmetro de configuração para a DLL do servidor. Cada chamada XcvData faz com que a função XcvDataPort do servidor seja chamada.
Chame ClosePrinter, especificando o identificador recebido do OpenPrinter. Isso faz com que a função XcvClosePort da DLL do servidor seja chamada.