Función WSCInstallProviderAndChains (ws2spi.h)

Artículo
03/04/2024

Nota

Los proveedores de servicios en capas están en desuso. A partir de Windows 8 y Windows Server 2012, use la Plataforma de filtrado de Windows. La función WSCInstallProviderAndChains instala el proveedor de transporte de 32 bits especificado, así como sus cadenas de protocolo específicas en la base de datos de configuración del sistema Winsock 2 en un equipo de 32 bits. Esta función garantiza que las cadenas de protocolos se ordenen al principio de la información de configuración del proveedor de transporte, lo que garantiza que no sea necesaria una llamada independiente a WSCWriteProviderOrder .

Sintaxis

int WSCInstallProviderAndChains(
  [in]            LPGUID              lpProviderId,
  [in]            const LPWSTR        lpszProviderDllPath,
  [in]            const LPWSTR        lpszLspName,
  [in]            DWORD               dwServiceFlags,
  [in]            LPWSAPROTOCOL_INFOW lpProtocolInfoList,
  [in]            DWORD               dwNumberOfEntries,
  [out, optional] LPDWORD             lpdwCatalogEntryId,
  [out]           LPINT               lpErrno
);

Parámetros

[in] lpProviderId

Puntero a un identificador único global (GUID) específico del proveedor.

[in] lpszProviderDllPath

Puntero a una cadena Unicode que contiene la ruta de acceso de carga al archivo DLL del proveedor. Esta cadena observa las reglas habituales para la resolución de rutas de acceso y puede contener cadenas de entorno insertadas (%SystemRoot%, por ejemplo). Estas cadenas de entorno se expanden siempre que Ws2_32.dll carga posteriormente el archivo DLL del proveedor en nombre de una aplicación. Una vez expandidas las cadenas de entorno incrustadas, Ws2_32.dll pasa la cadena resultante a la función LoadLibrary para cargar el proveedor en memoria. Para obtener más información, consulte LoadLibrary.

[in] lpszLspName

Puntero a una cadena Unicode que contiene el nombre del proveedor de sockets.

[in] dwServiceFlags

Marcas de servicio para el tipo de entrada de catálogo "ficticía" que se va a crear.

Una entrada ficticía es una estructura WSAProtocol_Info con el miembro ChainLen establecido en 0. La entrada de catálogo LSP real hará referencia al identificador de esta entrada ficticia en su miembro ProtocolChain .

Las marcas posibles que se pueden establecer para este parámetro son las siguientes:

Valor	Significado
XP1_IFS_HANDLES	La entrada de catálogo es para un LSP del sistema de archivos instalable (IFS), que devuelve identificadores de socket específicos de IFS. Estos identificadores se devuelven directamente a la aplicación que realiza la llamada. Un LSP de IFS no puede interceptar la finalización de las llamadas de Winsock y no tiene que tener implementadas o disponibles todas las funciones de Winsock.

[in] lpProtocolInfoList

Puntero a una matriz de estructuras de WSAProtocol_Info . Cada estructura define un protocolo, una familia de direcciones y un tipo de socket admitido por el proveedor. Los miembros de la estructura WSAPROTOCOL_INFO que se examinan son iProtocol, iAddressFamily e iSocketType.

[in] dwNumberOfEntries

Número de entradas de la matriz lpProtocolInfoList .

[out, optional] lpdwCatalogEntryId

Recibe un puntero a la entrada "ficticía" recién instalada para el proveedor de transporte en la base de datos de configuración del sistema Winsock 2. Este identificador se usa para instalar las entradas de catálogo para el LSP.

[out] lpErrno

Puntero que recibe un código de error generado por la llamada si se produce un error en la función.

Valor devuelto

Si
WSCInstallProviderAndChains se realiza correctamente, devuelve cero. De lo contrario, devuelve SOCKET_ERROR y se devuelve un código de error específico en el parámetro lpErrno .

Código de error	Significado
WSAEFAULT	Uno o varios de los argumentos no están en una parte válida del espacio de direcciones del usuario.
WSAEINVAL	Uno o varios argumentos no son válidos. Este error se devuelve para las siguientes condiciones: el parámetro lpProviderId es NULL, el parámetro lpszProviderDllPath no es válido o la longitud de la ruta de acceso es demasiado grande (MAX_PATH se ha superado), el parámetro lpszLspName no es válido o la longitud del nombre es demasiado grande (WSAPROTOCOL_LEN se supera), el lpProtocolInfoList se establece en un valor distinto de NULL y dwNumberOfEntries el parámetro es cero, ya existe un identificador de proveedor duplicado o el nombre del proveedor de servicios en capas en el catálogo, o no se puede encontrar una coincidencia para el protocolo, la familia de direcciones y el tipo de socket especificados.
WSAEINPROGRESS	Ya está en curso una instalación del proveedor.
WSAEINVALIDPROCTABLE	Falta la funcionalidad necesaria del proveedor.
WSAENOBUFS	No se puede asignar memoria para los búferes.
WSANO_RECOVERY	Error irrecuperable. Este error se devuelve en varias condiciones, incluido lo siguiente: el proveedor ya está instalado, el parámetro lpProtocolInfoList era NULL y no se encontró ningún proveedor base, se alcanzó la longitud máxima de la cadena de protocolo (MAX_PROTOCOL_CHAIN), el usuario carece de los privilegios administrativos necesarios para escribir en el registro winsock o se produjo un error al crear o instalar una entrada de catálogo.
WSASYSCALLFAILURE	Se ha producido un error en una llamada del sistema que nunca debería producir un error.

Comentarios

WSCInstallProviderAndChains es una versión mejorada de la función WSCInstallProvider básica que se usa para instalar un único proveedor de servicios de transporte. Si se instala un proveedor de servicios en capas, se debe usar WSCInstallProviderAndChains . WSCInstallProviderAndChains puede instalar un protocolo en capas y una o varias cadenas de protocolos con una sola llamada de función. Para realizar el mismo trabajo con WSCInstallProvider , se necesitarían varias llamadas de función.

Winsock 2 admite protocolos en capas. Un protocolo en capas es uno que implementa solo funciones de comunicaciones de nivel superior mientras se basa en una pila de transporte subyacente para el intercambio real de datos con un punto de conexión remoto. Un ejemplo de un protocolo en capas sería una capa de seguridad que agrega un protocolo al proceso de establecimiento de conexión para realizar la autenticación y establecer un esquema de cifrado mutuamente acordado. Por lo general, este protocolo de seguridad requeriría los servicios de un protocolo de transporte confiable subyacente, como TCP o SPX. El término protocolo base hace referencia a un protocolo como TCP o SPX que es capaz de realizar comunicaciones de datos con un punto de conexión remoto. El término protocolo en capas se usa para describir un protocolo que no puede ser independiente. A continuación, una cadena de protocolos se definiría como uno o varios protocolos en capas y anclados por un protocolo base. Un protocolo base tiene el miembro ChainLen de la estructura WSAProtocol_Info establecida en BASE_PROTOCOL que se define como 1. Un protocolo en capas tiene el miembro ChainLen de la estructura WSAPROTOCOL_INFO establecida en LAYERED_PROTOCOL que se define como cero. Una cadena de protocolos tiene el miembro ChainLen de la estructura de WSAPROTOCOL_INFO establecida en mayor que 1.

Si lpProtocolInfoList se establece en NULL, esta función crea cadenas de protocolo en las que el proveedor se superpone sobre el protocolo base para cada tipo de protocolo único tal y como se define en la familia de direcciones, el tipo de socket y el protocolo. Esto elimina la creación de entradas de proveedor duplicadas inaccesibles.

Si lpProtocolInfoList se establece en un valor distinto de NULL , esta función crea cadenas de protocolo obteniendo la entrada más alta en la información de configuración que coincide con la familia de direcciones, el tipo de socket y el protocolo de cada elemento de la matriz proporcionada. De nuevo, solo se tienen en cuenta la familia de direcciones, el tipo de socket y el protocolo; se omiten todos los demás miembros y duplicados.

Una vez finalizada correctamente esta llamada, las llamadas posteriores a WSAEnumProtocols o WSCEnumProtocols devolverán las entradas de la cadena de protocolo recién creadas. Tenga en cuenta que en entornos windows, solo las instancias de Ws_32.dll creadas mediante una llamada a WSAStartup después de que se complete correctamente WSCInstallProviderAndChains incluirán las nuevas entradas cuando WSAEnumProtocols y WSCEnumProtocols devuelvan.

Nota La función WSAEnumProtocols no enumera una entrada de protocolo superpuesta mientras WSCEnumProtocols sí.

Si se ejecuta correctamente, WSCInstallProviderAndChains intentará alertar a todas las aplicaciones interesadas que se han registrado para recibir notificaciones del cambio mediante una llamada a WSAProviderConfigChange.

Un usuario que inició sesión como miembro del grupo Administradores solo puede llamar a la función WSCInstallProviderAndChains . Si un usuario llama a WSCInstallProviderAndChains que no es miembro del grupo Administradores, se producirá un error en la llamada de función y se devolverá WSANO_RECOVERY en el parámetro lpErrno . En el caso de los equipos que ejecutan Windows Vista o Windows Server 2008, esta función también puede producir un error debido al control de cuentas de usuario (UAC). Si un usuario que ha iniciado sesión como miembro del grupo Administradores que no sea el administrador integrado ejecuta esta función, se producirá un error en esta llamada a menos que la aplicación se haya marcado en el archivo de manifiesto con un valor requestedExecutionLevel establecido en requireAdministrator. Si la aplicación en Windows Vista o Windows Server 2008 carece de este archivo de manifiesto, un usuario que inició sesión como miembro del grupo Administradores distinto del administrador integrado debe ejecutar la aplicación en un shell mejorado como administrador integrado (administrador de runas) para que esta función se realice correctamente.

La aplicación que realiza la llamada debe realizar cualquier instalación de archivos o configuración específica del proveedor.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h
Library	Ws2_32.lib
Archivo DLL	Ws2_32.dll