Función XcvDataPort (winsplp.h)

Artículo
03/13/2023

Una función XcvDataPort del archivo DLL del servidor de supervisión de puertos recibe información de y devuelve información a la DLL de la interfaz de usuario del monitor de puerto.

Sintaxis

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

Parámetros

[in] hXcv

Identificador de impresora proporcionado por el autor de la llamada, obtenido mediante una llamada a OpenPrinter (descrito en la documentación de Microsoft Windows SDK). Este identificador se crea y devuelve mediante la función XcvOpenPort .

[in] pszDataName

Puntero proporcionado por el autor de la llamada a una cadena que representa el nombre de los datos que se solicitan. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] pInputData

Puntero proporcionado por el autor de la llamada a un búfer que contiene datos de entrada.

cbInputData

Tamaño proporcionado por el autor de la llamada, en bytes, del búfer al que apunta pInputData.

[out] pOutputData

Puntero proporcionado por el autor de la llamada a un búfer para recibir datos de salida.

cbOutputData

Tamaño proporcionado por el autor de la llamada, en bytes, del búfer al que apunta pOutputData.

[out] pcbOutputNeeded

Puntero proporcionado por el autor de la llamada a una ubicación para recibir el tamaño mínimo, en bytes, necesario para el búfer al que apunta pOutputData.

Valor devuelto

Si la operación se realiza correctamente, esta función debe devolver ERROR_SUCCESS. De lo contrario, debe devolver un código de error win32 con prefijo ERROR_. El archivo DLL de la interfaz de usuario del monitor de impresión recibe este valor en la ubicación pdwStatus especificada para XcvData.

Comentarios

Los archivos DLL del servidor de supervisión de puertos son necesarios para definir una función XcvDataPort para que puedan recibir información de, y devolver información a, un archivo DLL de interfaz de usuario del monitor de puerto. La dirección de la función debe incluirse en una estructura MONITOR2 .

La función XcvDataPort se llama a la función XcvData del administrador de colas. Los parámetros de función para XcvDataPort y XcvData son casi idénticos. (XcvData tiene un parámetro adicional, pdwStatus, que no está presente en XcvDataPort).

La cadena a la que apunta pszDataName especifica la operación que se va a realizar. La función debe reconocer las siguientes cadenas de nombre de datos:

Cadena de nombre de datos	Operación
L"AddPort"	Se ha enviado toda la información necesaria para agregar un puerto. La función debe realizar operaciones necesarias para agregar el puerto especificado, incluida la escritura del nombre del puerto en el Registro en la clave Puertos. El parámetro pInputData apunta a una cadena de nombre de puerto terminada en NULL. Si la función devuelve ERROR_SUCCESS, el administrador de cola marca el puerto como agregado. La DLL de la interfaz de usuario del monitor de impresión especifica esta cadena desde su función AddPortUI .
L"DeletePort"	Se ha enviado toda la información necesaria para eliminar un puerto. La función debe realizar operaciones necesarias para eliminar el puerto especificado, incluida la eliminación del nombre del puerto de la clave ports del Registro. El parámetro pInputData apunta a una cadena de nombre de puerto terminada en NULL. Si la función devuelve ERROR_SUCCESS, el colador marca el puerto como eliminado. La DLL de la interfaz de usuario del monitor de impresión especifica esta cadena desde su función DeletePortUI .
L"MonitorUI"	La función debe usar pOutputData para devolver el nombre del archivo DLL de interfaz de usuario del monitor de puerto asociado. La cola de impresión especifica esta cadena cuando una aplicación llama a la función AddPort de Microsoft Windows SDK.

Normalmente, la función se escribe para reconocer cadenas adicionales y personalizadas enviadas por el archivo DLL de la interfaz de usuario desde sus funciones AddPortUI, ConfigurePortUI y DeletePortUI . Estas cadenas pueden representar comandos que solicitan valores de configuración actuales desde el archivo DLL del servidor o que entregan nuevos valores. Por ejemplo, la función XcvDataPort podría reconocer la cadena "GetTransmissionRetryTimeout", que el archivo DLL de interfaz de usuario podría enviar al archivo DLL del servidor para solicitar el valor de tiempo de espera de reintento de transmisión almacenado actualmente. O bien, puede definir un conjunto de cadenas que se deben enviar antes de enviar "AddPort" o "DeletePort", donde se usan las cadenas para proporcionar información que identifica el puerto que se va a agregar o eliminar.

Para una cadena pszDataName determinada y un búfer de entrada, se podría llamar primero a XcvDataPort con un valor cbOutputData de cero. La función debe devolver un tamaño de búfer necesario en pcbOutputNeeded, junto con un valor devuelto de ERROR_INSUFFICIENT_BUFFER. El autor de la llamada puede usar el valor recibido en pcbOutputNeeded para asignar un búfer de salida de tamaño adecuado y, a continuación, volver a llamar a XcvDataPort , esta vez especificando el tamaño del búfer asignado en cbOutputData.

La función XcvDataPort debe validar todos los argumentos de entrada. En concreto, la función debe:

Valide el contenido de la cadena a la que apunta el parámetro pszDataName . Si esta cadena representa una operación administrativa (normalmente agregar, eliminar o configurar un puerto), la función XcvDataPort debe comparar la máscara de acceso concedida recibida previamente por la función XcvOpenPort con SERVER_ACCESS_ADMINISTER. Si se produce un error en la comparación, XcvDataPort debe devolver ERROR_ACCESS_DENIED.
Valide el contenido del búfer al que apunta el parámetro pInputData . Cuando el administrador de colas llama a la función XcvOpenPort , no realiza ninguna validación en el contenido de este búfer. El monitor no puede realizar ninguna suposición sobre la validez de estos datos, que puede proceder de una aplicación malintencionada.

Si está escribiendo un monitor de puerto que se comunicará con TCPMON, consulte TcpMON Xcv Interface ( Interfaz Xcv de TCPMON).