Función WSPStartup (ws2spi.h)

La función WSPStartup inicia el uso de una interfaz de proveedor de servicios (SPI) de Windows Sockets por parte de un cliente.

Sintaxis

int WSPStartup(
  [in]  WORD                wVersionRequested,
  [out] LPWSPDATA           lpWSPData,
  [in]  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  [in]  WSPUPCALLTABLE      UpcallTable,
  [out] LPWSPPROC_TABLE     lpProcTable
);

Parámetros

[in] wVersionRequested

La versión más alta de SPI de Windows Sockets admite que el autor de la llamada pueda usar. El byte de orden superior especifica el número de versión secundaria (revisión); el byte de orden bajo especifica el número de versión principal.

[out] lpWSPData

Puntero a una estructura de datos WSPDATA que recibe información sobre el proveedor de servicios de Windows Sockets.

[in] lpProtocolInfo

Puntero a una estructura WSAProtocol_Info que define las características del protocolo deseado. Esto es especialmente útil cuando un único proveedor DLL es capaz de crear instancias de varios proveedores de servicios diferentes.

[in] UpcallTable

La tabla de distribución de llamadas upcall de Winsock 2 (Ws2_32.dll) pasada en una estructura WSPUpCallTable .

[out] lpProcTable

Puntero a la tabla de punteros de función SPI. Esta tabla se devuelve como una estructura WSPProc_Table .

Valor devuelto

La función WSPStartup devuelve cero si se ejecuta correctamente. De lo contrario, devuelve uno de los códigos de error que se enumeran a continuación.

Comentarios

Los proveedores de servicios de transporte de Windows Sockets 2 son archivos DLL con un único punto de entrada de procedimiento exportado, WSPStartup, que se usa para la función de inicialización del proveedor de servicios. Todas las demás funciones del proveedor de servicios son accesibles para el archivo DLL de Winsock 2 a través de la tabla de distribución del proveedor de servicios que se pasa en el parámetro lpProcTable a la función WSPStartup . El archivo DLL del proveedor de servicios se carga en la memoria por el archivo DLL de WinSock 2 solo cuando es necesario y se descarga cuando sus servicios ya no son necesarios.

La interfaz del proveedor de servicios también define varias circunstancias en las que un proveedor de servicios de transporte llama al archivo DLL de Winsock 2 (llamadas ascendentes) para obtener servicios de soporte técnico de DLL. El proveedor de servicios de transporte se devuelve la tabla de distribución upcall para el archivo DLL winsock 2 en el parámetro UpcallTable pasado a la función WSPStartup .

La función WSPStartup debe ser la primera función SPI de Windows Sockets a la que llama un cliente SPI de Windows Sockets por proceso. Permite al cliente especificar la versión de SPI de Windows Sockets necesario y proporcionar su tabla de distribución de llamadas ascendentes. Todas las llamadas ascendentes (es decir, las funciones prefijos con WPU) realizadas por el proveedor de servicios de Windows Sockets se invocan a través de la tabla de distribución de llamadas ascendentes del cliente. Esta función también permite al cliente recuperar detalles de la implementación específica del proveedor de servicios de Windows Sockets. El cliente SPI de Windows Sockets solo puede emitir más funciones SPI de Windows Sockets después de una invocación WSPStartup correcta. Una tabla de punteros al resto de las funciones SPI se recupera a través del parámetro lpProcTable que devuelve una estructura WSPProc_Table .

El archivo DLL de Winsock 2 carga el archivo DLL de interfaz del proveedor de servicios en el sistema mediante los mecanismos de carga de la biblioteca dinámica estándar de Windows e inicializa mediante una llamada a la función WSPStartup . Normalmente, esto se desencadena mediante una aplicación que llama a la función socket o WSASocket para crear un nuevo socket que se va a asociar a un proveedor de servicios cuyo archivo DLL de interfaz no está cargado actualmente en la memoria.

Para admitir versiones futuras del SPI de Windows Sockets y el Ws2_32.dll, que pueden tener diferencias funcionales con respecto al SPI de Windows Sockets actual, se realiza una negociación en WSPStartup. El autor de la llamada de WSPStartup (ya sea el Ws2_32.dll o un protocolo superpuesta) y el proveedor de servicios de Windows Sockets indican entre sí la versión más alta de Windows Sockets que pueden admitir y cada una confirma que la versión más alta del otro es aceptable. Tras la entrada a WSPStartup, el proveedor de servicios de Windows Sockets examina la versión solicitada por el cliente. Si esta versión es igual o superior a la versión más baja admitida por el proveedor de servicios, la llamada se realiza correctamente y el proveedor de servicios devuelve en el miembro wHighVersion de la estructura WSPDATA la versión más alta que admite y en el miembro wVersion el mínimo de su versión alta y versión especificada en el parámetro wVersionRequested . A continuación, el proveedor de servicios Windows Sockets supone que el cliente SPI de Windows Sockets usará la versión de Windows Sockets especificada en el miembro wVersion . Si el miembro wVersion de la estructura WSPDATA es inaceptable para el autor de la llamada, debe llamar a LPWSPCleanup y buscar otro proveedor de servicios de Windows Sockets o no se puede inicializar.

Esta negociación permite que un proveedor de servicios de Windows Sockets y un cliente SPI de Windows Sockets admitan una variedad de versiones de Windows Sockets. Un cliente puede usar correctamente un proveedor de servicios de Windows Sockets si hay alguna superposición en los intervalos de versiones.

La versión actual de la especificación de Windows Sockets es la versión 2.2. El archivo DLL de Winsock actual, Ws2_32.dll, admite aplicaciones que solicitan cualquiera de las siguientes versiones de la especificación de Windows Sockets:

• 1.0
• 1.1
• 2.0
• 2.1
• 2.2

Para obtener acceso completo a la nueva sintaxis de una versión superior de la especificación de Windows Sockets, la aplicación debe negociar esta versión superior. En este caso, el parámetro wVersionRequested debe establecerse en request version 2.2. La aplicación también debe cumplir completamente esa versión superior de la especificación de Windows Socket, como compilar en el archivo de encabezado adecuado, vincular con una nueva biblioteca u otros casos especiales. El archivo de encabezado Winsock2.h para la compatibilidad con Winsock 2 se incluye con Microsoft Kit de desarrollo de software de Windows (SDK).

Windows Sockets versión 2.2 es compatible con Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 con Service Pack 4 (SP4) y versiones posteriores, Windows Me, Windows 98 y Windows 95 OSR2. Windows Sockets versión 2.2 también se admite en
Windows 95 con la actualización de Windows Socket 2. Las aplicaciones de estas plataformas normalmente deben solicitar Winsock 2.2 estableciendo el parámetro wVersionRequested en consecuencia.

En Windows 95 y versiones de Windows NT 3.51 y versiones anteriores, Windows Sockets versión 1.1 es la versión más alta de la especificación de Windows Sockets admitida.

Es legal y posible que una aplicación o dll escrita use una versión inferior de la especificación de Windows Sockets compatible con el ARCHIVO DLL de Winsock para negociar correctamente esta versión inferior mediante la función WSPStartup . Por ejemplo, una aplicación puede solicitar la versión 1.1 en el parámetro wVersionRequested pasado a la función WSPStartup en una plataforma con el archivo DLL winsock 2.2. En este caso, la aplicación solo debe basarse en características que se ajusten a la versión solicitada. Los nuevos códigos Ioctl, el nuevo comportamiento de las funciones existentes y las nuevas funciones no deben usarse. La negociación de versiones proporcionada por WSPStartup se usó principalmente para permitir que las aplicaciones anteriores de Winsock 1.1 desarrolladas para Windows 95 y Windows NT 3.51 y versiones anteriores se ejecutaran con el mismo comportamiento en versiones posteriores de Windows. El archivo de encabezado Winsock.h para la compatibilidad con Winsock 1.1 se incluye con el Windows SDK.

En el siguiente gráfico se proporcionan ejemplos de cómo funciona WSPStartup junto con diferentes versiones de proveedor de servicios de Windows Sockets y WS2_32.DLL.

El siguiente fragmento de código muestra cómo un cliente SPI de Windows Sockets, que solo admite la versión 2 de SPI de Windows Sockets, realiza una llamada WSPStartup :

WORD wVersionRequested;
WSPDATA WSPData;
 
int err;
 
WSPUPCALLTABLE upcallTable =
{ 
    /* initialize upcallTable with function pointers */
};
 
LPWSPPROC_TABLE lpProcTable =
{ 
    /* allocate memory for the ProcTable */
};
 
wVersionRequested = MAKEWORD( 2, 2 );
 
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    return;
}
 
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider supports versions */
/* greater than 2.2 in addition to 2.2, it will still */
/* return 2.2 in wVersion since that is the version we  */
/* requested.                                           */
 
if ( LOBYTE( WSPData.wVersion ) != 2 ||
         HIBYTE( WSPData.wVersion ) != 2 ) {
    /* Tell the user that we could not find a usable */
    /* Windows Sockets service provider.                     */
    LPWSPCleanup( );
    return;   
}
 
/* The Windows Sockets service provider is acceptable. Proceed. */

Y este fragmento de código muestra cómo un proveedor de servicios de Windows Sockets que solo admite la versión 2.2 realiza la negociación WSPStartup :

/* Make sure that the version requested is >= 2.2.  */
/* The low byte is the major version and the high   */
/* byte is the minor version.                       */
 
if ( (LOBYTE( wVersionRequested ) < 2) ||
     ((LOBYTE( wVersionRequested ) == 2) &&
     (HIBYTE( wVersionRequested ) < 2))) {
    return WSAVERNOTSUPPORTED;
}
 
/* Since we only support 2.2, set both wVersion and  */
/* wHighVersion to 2.2.                              */
 
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );

Una vez que el cliente SPI de Windows Sockets ha realizado una llamada WSPStartup correcta, puede continuar realizando otras llamadas SPI de Windows Sockets según sea necesario. Cuando haya terminado de usar los servicios del proveedor de servicios de Windows Sockets, el cliente debe llamar a LPWSPCleanup para permitir que el proveedor de servicios de Windows Sockets libere los recursos asignados para el cliente.

La función WSPStartup debe llamarse al menos una vez por cada proceso de cliente y puede llamarse varias veces por el ARCHIVO DLL de Winsock 2 u otras entidades. Se debe llamar a una función LPWSPCleanup correspondiente para cada llamada WSPStartup correcta. El proveedor de servicios debe mantener un recuento de referencias por proceso. En cada llamada WSPStartup , el autor de la llamada puede especificar cualquier número de versión admitido por el archivo DLL del proveedor de servicios.

Un proveedor de servicios debe almacenar el puntero a la tabla de distribución de llamadas ascendentes del cliente que se recibe como parámetro UpcallTable mediante la función WSPStartup por proceso. Si un proceso determinado llama a WSPStartup varias veces, el proveedor de servicios solo debe usar el puntero de tabla de envío de llamadas proporcionado más recientemente.

Un cliente SPI de Windows Sockets puede llamar a WSPStartup más de una vez si necesita obtener la información de estructura WSPDATA más de una vez. En cada llamada de este tipo, el cliente puede especificar cualquier número de versión admitido por el proveedor.

Debe haber una llamada LPWSPCleanup correspondiente a cada llamada WSPStartup correcta para permitir que los archivos DLL de terceros usen un proveedor de Windows Sockets. Esto significa, por ejemplo, que si se llama a WSPStartup tres veces, la llamada correspondiente a LPWSPCleanup debe producirse tres veces. Las dos primeras llamadas a LPWSPCleanup no hacen nada excepto disminuir un contador interno; La llamada de LPWSPCleanup final realiza toda la desasignación de recursos necesaria.

Esta función (y la mayoría de las demás funciones del proveedor de servicios) se pueden invocar en un subproceso que se inició como un proceso de 16 bits si el cliente es un cliente de Windows Sockets 1.1 de 16 bits. Una limitación importante de los procesos de 16 bits es que un proceso de 16 bits no puede crear subprocesos. Esto es importante para los implementadores de proveedores de servicios que planean usar un subproceso de servicio interno como parte de la implementación.

Afortunadamente, normalmente solo hay dos áreas en las que las condiciones de un subproceso de servicio son fuertes:

• En la implementación de la finalización de E/S superpuesta.
• En la implementación de LPWSPEventSelect.

Ambas áreas solo son accesibles a través de nuevas funciones de Windows Sockets 2, que solo los procesos de 32 bits pueden invocar.

Un subproceso de servicio se puede usar de forma segura si se siguen cuidadosamente estas dos reglas de diseño:

• Use un subproceso de servicio solo para la funcionalidad que no está disponible para clientes de Windows Sockets 1.1 de 16 bits.
• Cree el subproceso de servicio solo a petición.

Se aplican otras precauciones al uso de subprocesos de servicio internos. En primer lugar, los subprocesos suelen conllevar cierta penalización de rendimiento. Use lo menos posible y evite las transiciones de subproceso siempre que sea posible. En segundo lugar, el código siempre debe comprobar si hay errores en la creación de subprocesos y generar errores de forma correcta e informativa (por ejemplo, con WSAEOPNOTSUPP) en caso de que algún evento de ejecución que no esperaba generara un proceso de 16 bits que ejecutase una ruta de acceso de código que necesita subprocesos.

Un proveedor de servicios en capas proporciona una implementación de esta función, pero también es un cliente de esta función cuando llama a WSPStartup para inicializar la siguiente capa en la cadena de protocolos. La llamada al WSPStartup de la capa siguiente puede producirse durante la ejecución de WSPStartup de esta capa o se puede retrasar y llamar a petición, como cuando se llama a LPWSPSocket . En cualquier caso, algunas consideraciones especiales se aplican al parámetro lpProtocolInfo de esta función, ya que se propaga a través de las capas de la cadena de protocolos.

El proveedor en capas busca en ProtocolChain la estructura a la que hace referencia lpProtocolInfo para determinar su propia ubicación en la cadena (buscando el propio identificador de entrada de catálogo de la capa) y la identidad del siguiente elemento de la cadena. Si el siguiente elemento es otra capa, cuando se llama al WSPStartup de la capa siguiente, esta capa debe pasar a la capa siguiente un lpProtocolInfo que haga referencia a la misma estructura de WSAProtocol_Info sin modificar con la misma información de cadena sin modificar. Sin embargo, si la capa siguiente es el protocolo base (es decir, el último elemento de la cadena), esta capa realiza una sustitución al llamar al WSPStartup del proveedor base. En este caso, el parámetro lpProtocolInfo debe hacer referencia a la estructura WSAPROTOCOL_INFO del proveedor base.

Una ventaja fundamental de esta directiva es que los proveedores de servicios base no tienen que ser conscientes de las cadenas de protocolos.

Esta misma directiva de propagación se aplica al propagar una estructura de WSAPROTOCOL_INFO a través de una secuencia por capas de otras funciones, como LPWSPAddressToString, LPWSPDuplicateSocket, LPWSPSocket o LPWSPStringToAddress.

Requisitos

Consulte también

WSAProtocol_Info

LPWSPAddressToString

LPWSPStringToAddress

LPWSPCleanup

LPWSPDuplicateSocket

LPWSPEventSelect

WSPProc_Table

LPWSPSend

LPWSPSendTo

LPWSPSocket

WSPUpCallTable