Funzione XcvDataPort (winsplp.h)

Articolo
03/13/2023

La funzione XcvDataPort di una DLL del server di monitoraggio delle porte riceve informazioni da 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 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 ulteriori informazioni, vedere la sezione Osservazioni successiva.

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

Commenti

Le DLL del server di monitoraggio delle porte sono necessarie per definire una funzione XcvDataPort in modo che possano 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 XcvData dello spooler. I parametri della funzione per XcvDataPort e XcvData sono quasi identici. XcvData ha un parametro aggiuntivo, pdwStatus, che 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 nella 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 monitor 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, dalla 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 Microsoft Windows SDK AddPort.

In genere, la funzione viene scritta per riconoscere stringhe aggiuntive personalizzate inviate dalla DLL dell'interfaccia utente all'interno delle funzioni AddPortUI, ConfigurePortUI e DeletePortUI . Queste stringhe possono rappresentare comandi che richiedono i 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 della 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 una determinata stringa pszDataName e il buffer di input, XcvDataPort può essere chiamato per la prima volta 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 nuovamente 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 aggiunta, eliminazione o configurazione di 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 ha esito negativo, 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 delle porte che comunicherà con TCPMON, vedere Interfaccia Xcv TCPMON.