Funzione XcvDataPort (winsplp.h)

Articolo
02/07/2025

Una DLL del server di monitoraggio delle porte funzione XcvDataPort riceve informazioni e restituisce informazioni alla DLL dell'interfaccia utente del monitoraggio delle porte.

Sintassi

DWORD XcvDataPort(
  _In_  HANDLE  hXcv,
  _In_  LPCWSTR pszDataName,
  _In_  PBYTE   pInputData,
        DWORD   cbInputData,
  _Out_ PBYTE   pOutputData,
        DWORD   cbOutputData,
  _Out_ PDWORD  pcbOutputNeeded
);

Parametri

[in] hXcv

Handle della stampante fornito dal chiamante, ottenuto chiamando OpenPrinter (descritto nella documentazione di Microsoft Windows SDK). Questo handle viene creato e restituito dalla funzione XcvOpenPort.

[in] pszDataName

Puntatore fornito dal chiamante a una stringa che rappresenta il nome dei dati richiesti. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in] pInputData

Puntatore fornito dal chiamante a un buffer contenente i dati di input.

cbInputData

Dimensioni fornite dal chiamante, in byte, del buffer a cui punta pInputData.

[out] pOutputData

Puntatore fornito dal chiamante a un buffer per ricevere i dati di output.

cbOutputData

Dimensioni fornite dal chiamante, in byte, del buffer a cui punta pOutputData.

[out] pcbOutputNeeded

Puntatore fornito dal chiamante a una posizione per ricevere le dimensioni minime, in byte, necessarie per il buffer a cui punta pOutputData.

Valore restituito

Se l'operazione ha esito positivo, questa funzione deve restituire ERROR_SUCCESS. In caso contrario, deve restituire un codice di errore Win32 con prefisso ERROR_. La DLL dell'interfaccia utente del monitoraggio di stampa riceve questo valore nel percorso pdwStatus specificato per XcvData.

Osservazioni

Le DLL del server di monitoraggio delle porte sono necessarie per definire una funzione XcvDataPort in modo da poter ricevere informazioni e restituire informazioni a una DLL dell'interfaccia utente di monitoraggio delle porte. L'indirizzo della funzione deve essere incluso in una struttura MONITOR2.

La funzione XcvDataPort viene chiamata dalla funzione di XcvData del spooler. I parametri della funzione per XcvDataPort e XcvData sono quasi identici. (XcvData ha un parametro aggiuntivo, pdwStatus, non presente in XcvDataPort.

La stringa a cui punta pszDataName specifica l'operazione da eseguire. La funzione deve riconoscere le stringhe di nome dati seguenti:

Stringa nome dati	Operazione
L"AddPort"	Tutte le informazioni necessarie per l'aggiunta di una porta sono state inviate. La funzione deve eseguire operazioni necessarie per aggiungere la porta specificata, inclusa la scrittura del nome della porta nel Registro di sistema sotto la chiave Ports. Il parametro pInputData punta a una stringa di nome porta con terminazione NULL. Se la funzione restituisce ERROR_SUCCESS, lo spooler contrassegna la porta come aggiunta. Questa stringa viene specificata dalla DLL dell'interfaccia utente del monitoraggio di stampa, dall'interno della relativa funzione AddPortUI.
L"DeletePort"	Tutte le informazioni necessarie per eliminare una porta sono state inviate. La funzione deve eseguire operazioni necessarie per eliminare la porta specificata, inclusa la rimozione del nome della porta dalla chiave Ports del Registro di sistema. Il parametro pInputData punta a una stringa di nome porta con terminazione NULL. Se la funzione restituisce ERROR_SUCCESS, lo spooler contrassegna la porta come eliminata. Questa stringa viene specificata dalla DLL dell'interfaccia utente del monitoraggio di stampa, dall'interno della relativa funzione DeletePortUI.
L"MonitorUI"	La funzione deve usare pOutputData per restituire il nome della DLL dell'interfaccia utente di Monitoraggio porte associata. Questa stringa viene specificata dallo spooler di stampa quando un'applicazione chiama la funzione di AddPort di Microsoft Windows SDK.

In genere, la funzione viene scritta per riconoscere stringhe personalizzate aggiuntive inviate dalla DLL dell'interfaccia utente all'interno delle funzioni AddPortUI, ConfigurePortUIe DeletePortUI. Queste stringhe possono rappresentare comandi che richiedono valori di configurazione correnti dalla DLL del server o che recapitano nuovi valori. Ad esempio, la funzione XcvDataPort potrebbe riconoscere la stringa "GetTransmissionRetryTimeout", che la DLL dell'interfaccia utente potrebbe inviare alla DLL del server per richiedere il valore di timeout dei tentativi di trasmissione attualmente archiviato. In alternativa, è possibile definire un set di stringhe che devono essere inviate prima dell'invio di "AddPort" o "DeletePort", in cui le stringhe vengono usate per fornire informazioni che identificano la porta da aggiungere o eliminare.

Per un determinato pszDataName stringa e buffer di input, XcvDataPort potrebbe essere prima chiamato con un valore cbOutputData pari a zero. La funzione deve restituire una dimensione del buffer necessaria in pcbOutputNeeded, insieme a un valore restituito di ERROR_INSUFFICIENT_BUFFER. Il chiamante può usare il valore ricevuto in pcbOutputNeeded per allocare un buffer di output di dimensioni adeguate e può quindi chiamare di nuovo XcvDataPort, questa volta specificando la dimensione del buffer allocata in cbOutputData.

La funzione XcvDataPort deve convalidare tutti gli argomenti di input. In particolare, la funzione deve:

Convalidare il contenuto della stringa a cui punta il parametro pszDataName. Se questa stringa rappresenta un'operazione amministrativa (in genere aggiungendo, eliminando o configurando una porta), la funzione XcvDataPort deve confrontare la maschera di accesso concessa ricevuta in precedenza dalla funzione XcvOpenPort con SERVER_ACCESS_ADMINISTER. Se il confronto non riesce, XcvDataPort deve restituire ERROR_ACCESS_DENIED.
Convalidare il contenuto del buffer a cui punta il parametro pInputData. Quando lo spooler chiama la funzione XcvOpenPort, non esegue alcuna convalida sul contenuto del buffer. Il monitoraggio non può fare ipotesi sulla validità di questi dati, che possono provenire da un'applicazione dannosa.

Se si scrive un monitor porta che comunicherà con TCPMON, vedere 'interfaccia Xcv TCPMON.