Funzione AddPortUI (winsplp.h)

Articolo
08/08/2023

La funzione AddPortUI di una DLL dell'interfaccia utente di monitoraggio delle porte aggiunge una porta della stampante, quindi ottiene le informazioni di configurazione della porta dall'utente e la invia alla DLL del server di monitoraggio delle porte.

Sintassi

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

Parametri

[in, optional] pszServer

Puntatore fornito dal chiamante a una stringa che rappresenta un nome del server o NULL se la stampante è locale.

[in] hWnd

Handle fornito dal chiamante della finestra da utilizzare come elemento padre per le finestre di dialogo. Se NULL, non devono essere visualizzate finestre di dialogo.

pszMonitorNameIn

Puntatore fornito dal chiamante a una stringa che rappresenta il nome del monitoraggio. Può essere NULL.

[out, optional] ppszPortNameOut

Puntatore fornito dal chiamante a una posizione per ricevere una stringa di nome porta. Può essere NULL, nel qual caso non viene restituito un nome.

Valore restituito

Se l'operazione ha esito positivo, la funzione deve restituire TRUE. In caso contrario, è necessario chiamare SetLastError per specificare un codice di errore e la funzione deve restituire FALSE. Se l'operazione viene annullata dall'utente o non è supportata, la funzione deve chiamare SetLastError(ERROR_CANCELLED), quindi restituire FALSE.

Commenti

Le DLL dell'interfaccia utente di Monitoraggio porte sono necessarie per definire una funzione AddPortUI e includere l'indirizzo della funzione in una struttura MONITORUI .

Lo spooler chiama AddPortUI dall'interno della relativa funzione AddPort. I primi tre argomenti ricevuti da AddPortUI sono gli argomenti ricevuti da AddPort. La funzione AddPort è descritta nella documentazione di Microsoft Windows SDK.

La funzione deve eseguire le operazioni seguenti:

Chiamare OpenPrinter, specificando un nome di stampante con il formato seguente:

\\NomeServer\,XcvMonitorMonitorName

dove ServerName e MonitorName sono i nomi del server e monitor ricevuti come argomenti della funzione AddPortUI .

La chiamata a OpenPrinter richiede una struttura PRINTER_DEFAULTS, descritta nella documentazione di Windows SDK. Il membro DesiredAccess della struttura deve essere impostato su SERVER_ACCESS_ADMINISTER. I membri pDatatype e pDevMode possono essere NULL.

Questa chiamata fa sì che venga chiamata la funzione XcvOpenPort della DLL del server di monitoraggio di stampa.
Ottenere un nome di porta dall'utente visualizzando una finestra di dialogo.
Chiamare XcvData, specificando gli argomenti di input seguenti:
- Handle ricevuto da OpenPrinter
- Nome della porta ricevuto dall'utente
- Stringa di nome dati personalizzata, ad esempio "PortExists"
Questa chiamata fa sì che venga chiamata la funzione XcvDataPort della DLL del server. La funzione XcvDataPort deve restituire un valore che indica se il nome della porta specificato è già stato usato. In caso affermativo, la DLL dell'interfaccia utente deve richiedere un altro nome all'utente e chiamare di nuovo XcvData .
Dopo aver ricevuto un nuovo nome di porta valido, chiamare nuovamente XcvData , questa volta specificando gli argomenti di input seguenti
- Handle ricevuto da OpenPrinter
- Nome della porta convalidato ricevuto dall'utente
- Stringa del nome dati "AddPort"
Questa chiamata fa sì che la funzione XcvDataPort della DLL del server venga chiamata nuovamente.
Ottenere i parametri di configurazione della porta dall'utente visualizzando una finestra di dialogo.
Chiamare XcvData una o più volte, specificando stringhe di nome dati personalizzate, per inviare ogni parametro di configurazione alla DLL del server. Ogni chiamata XcvData fa sì che venga chiamata la funzione XcvDataPort del server.
Chiamare ClosePrinter, specificando l'handle ricevuto da OpenPrinter. In questo modo viene chiamata la funzione XcvClosePort della DLL del server.