código de control de SIO_QUERY_TRANSPORT_SETTING

Artículo
06/12/2023

Descripción

El código de control SIO_QUERY_TRANSPORT_SETTING consulta la configuración de transporte en un socket.

Para realizar esta operación, llame a la función WSAIoctl o WSPIoctl con los parámetros siguientes.

int WSAIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
);

int WSPIoctl(
  (socket) s,             // descriptor identifying a socket
  SIO_QUERY_TRANSPORT_SETTING, // dwIoControlCode
  (LPVOID) lpvInBuffer,  // pointer to the input buffer
  (DWORD) cbInBuffer,    // size, in bytes, of the input buffer
  (LPVOID) lpvOutBuffer,     // pointer to the output buffer
  (DWORD) cbOutBuffer,       // size of output buffer
  (LPDWORD) lpcbBytesReturned,    // number of bytes returned
  (LPWSAOVERLAPPED) lpOverlapped,   // OVERLAPPED structure
  (LPWSAOVERLAPPED_COMPLETION_ROUTINE) lpCompletionRoutine,  // completion routine
  (LPWSATHREADID) lpThreadId,   // a WSATHREADID structure
  (LPINT) lpErrno   // a pointer to the error code.
);

Parámetros

s

Descriptor que identifica un socket.

dwIoControlCode

Código de control de la operación. Use SIO_QUERY_TRANSPORT_SETTING para esta operación.

lpvInBuffer

Puntero al búfer de entrada. Este parámetro contiene un puntero a una estructura donde el primer miembro de la estructura es una estructura TRANSPORT_SETTING_ID que determina qué configuración de transporte se consulta.

cbInBuffer

Tamaño, en bytes, del búfer de entrada. Este parámetro depende de la configuración de transporte que se consulta.

lpvOutBuffer

Puntero al búfer de salida. Este parámetro depende de la configuración de transporte que se consulta si los parámetros lpOverlapped y lpCompletionRoutine son NULL.

cbOutBuffer

Tamaño, en bytes, del búfer de salida.

lpcbBytesReturned

Puntero a una variable que recibe el tamaño, en bytes, de los datos almacenados en el búfer de salida.

Si el búfer de salida es demasiado pequeño, se produce un error en la llamada, WSAGetLastError devuelve WSAEINVAL y el parámetro lpcbBytesReturned apunta a un valor DWORD de cero.

Si lpOverlapped es NULL, el valor DWORD al que apunta el parámetro lpcbBytesReturned devuelto en una llamada correcta no puede ser cero.

Si el parámetro lpOverlapped no es NULL para sockets superpuestos, las operaciones que no se pueden completar inmediatamente se iniciarán y la finalización se indicará en un momento posterior. El valor DWORD al que apunta el parámetro lpcbBytesReturned que se devuelve puede ser cero, ya que el tamaño de los datos almacenados no se puede determinar hasta que se haya completado la operación superpuesta. El estado de finalización final se puede recuperar cuando se señala el método de finalización adecuado cuando se ha completado la operación.

lpvOverlapped

Puntero a una estructura WSAOVERLAPPED .

Si el socket s se creó sin el atributo superpuesto, se omite el parámetro lpOverlapped .

Si se abrió s con el atributo superpuesto y el parámetro lpOverlapped no es NULL, la operación se realiza como una operación superpuesta (asincrónica). En este caso, el parámetro lpOverlapped debe apuntar a una estructura WSAOVERLAPPED válida.

Para las operaciones superpuestas, la función WSAIoctl o WSPIoctl devuelve inmediatamente y el método de finalización adecuado se señala cuando se ha completado la operación. De lo contrario, la función no devuelve hasta que se haya completado la operación o se produzca un error.

lpCompletionRoutine

Tipo: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

Puntero a la rutina de finalización a la que se llama cuando se ha completado la operación (se omite para sockets no superpuestos).

lpThreadId

Puntero a una estructura WSATHREADID que usará el proveedor en una llamada posterior a WPUQueueApc. El proveedor debe almacenar la estructura WSATHREADID a la que se hace referencia (no el puntero a la misma) hasta después de que la función WPUQueueApc devuelva.

Nota Este parámetro solo se aplica a la función WSPIoctl .

lpErrno

Puntero al código de error.

Nota Este parámetro solo se aplica a la función WSPIoctl .

Valor devuelto

Si la operación se completa correctamente, la función WSAIoctl o WSPIoctl devuelve cero.

Si se produce un error en la operación o está pendiente, la función WSAIoctl o WSPIoctl devuelve SOCKET_ERROR. Para obtener información de error extendida, llame a WSAGetLastError.

Código de error	Significado
ERROR_INSUFFICIENT_BUFFER	El área de datos que se pasa a una llamada del sistema es demasiado pequeña. Este error se devuelve si el búfer apuntado por el parámetro lpvOutBuffer con un tamaño de búfer pasado en el parámetro cbOutBuffer es demasiado pequeño. El tamaño del búfer necesario se devolverá en el parámetro lpcbBytesReturned .
WSA_IO_PENDING	Una operación superpuesta se inició correctamente y la finalización se indicará en un momento posterior.
WSA_OPERATION_ABORTED	Se canceló una operación superpuesta debido al cierre del socket o a la ejecución del comando SIO_FLUSH IOCTL.
WSAEFAULT	El parámetro lpvOutBuffer, lpcbBytesReturned, lpOverlapped o lpCompletionRoutine no está totalmente incluido en una parte válida del espacio de direcciones del usuario.
WSAEINPROGRESS	La función se invoca cuando una devolución de llamada está en curso.
WSAEINTR	Se interrumpió una operación de bloqueo.
WSAEINVAL	El parámetro dwIoControlCode no es un comando válido o un parámetro de entrada especificado no es aceptable o el comando no es aplicable al tipo de socket especificado.
WSAENETDOWN	Error en el subsistema de red.
WSAENOPROTOOPT	La opción socket no se admite en el protocolo especificado.
WSAENOTCONN	El socket s no está conectado.
WSAENOTSOCK	El descriptor s no es un socket.
WSAEOPNOTSUPP	No se admite el comando IOCTL especificado. Este error se devuelve si el proveedor de transporte no admite el SIO_QUERY_TRANSPORT_SETTING IOCTL.

Comentarios

El SIO_QUERY_TRANSPORT_SETTING IOCTL se admite en Windows 8 y Windows Server 2012 y versiones posteriores del sistema operativo.

El SIO_QUERY_TRANSPORT_SETTING IOCTL es un IOCTL genérico que se usa para consultar la configuración de transporte en un socket. La configuración de transporte que se consulta se basa en el TRANSPORT_SETTING_ID pasado en el parámetro lpvInBuffer .

La única configuración de transporte que define actualmente es para la funcionalidad REAL_TIME_NOTIFICATION_CAPABILITY en un socket TCP.

Si el TRANSPORT_SETTING_ID pasado en el parámetro lpvInBuffer tiene el miembro Guid establecido en REAL_TIME_NOTIFICATION_CAPABILITY, se trata de una solicitud para consultar la configuración de notificación en tiempo real del socket TCP usado con controlChannelTrigger para recibir notificaciones de red en segundo plano en una aplicación de la Tienda Windows. El parámetro lpvInBuffer debe apuntar a una estructura de TRANSPORT_SETTING_ID . El parámetro lpvOutBuffer debe apuntar a una estructura de REAL_TIME_NOTIFICATION_SETTING_OUTPUT . Esta configuración de transporte solo se aplica a los sockets TCP. Esta configuración de transporte proporciona una manera de que WinInet o servicios de red similares consulten un socket TCP determinado para determinar el estado ControlChannelTrigger . Una aplicación de la Tienda Windows no llamará directamente a este IOCTL. Si la llamada WSAIoctl o WSPIoctl se realiza correctamente, este IOCTL devuelve una estructura de REAL_TIME_NOTIFICATION_SETTING_OUTPUT con el estado actual.

El SIO_QUERY_TRANSPORT_SETTING IOCTL proporciona una manera de que WinInet o servicios de red similares consulten el estado de configuración de transporte de un socket TCP determinado para determinar si ControlChannelTrigger está habilitado en el socket. Una aplicación de la Tienda Windows no llamará directamente a este IOCTL.

Este IOCTL solo se aplica a los sockets TCP.