Función RpcServerRegisterIf2 (rpcdce.h)

Artículo
03/15/2023

La función RpcServerRegisterIf2 registra una interfaz con la biblioteca en tiempo de ejecución rpc.

Sintaxis

RPC_STATUS RpcServerRegisterIf2(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  unsigned int       MaxRpcSize,
  RPC_IF_CALLBACK_FN *IfCallbackFn
);

Parámetros

IfSpec

Estructura generada por MIDL que indica la interfaz que se va a registrar.

MgrTypeUuid

Puntero a un UUID de tipo que se va a asociar con el parámetro MgrEpv . Si se especifica un valor de parámetro null (o un UUID nulo) se registra IfSpec con un UUID de tipo nulo.

MgrEpv

Vector de punto de entrada (EPV) de las rutinas de administrador. Para usar el EPV predeterminado generado por MIDL, especifique un valor NULL . Para obtener más información, consulte RPC_MGR_EPV.

Flags

Banderas. Para obtener una lista de valores de marca, vea Marcas de registro de interfaz.

MaxCalls

Número máximo de solicitudes simultáneas de llamadas a procedimientos remotos que el servidor puede aceptar en una interfaz de escucha automática . El parámetro MaxCalls solo es aplicable en una interfaz de escucha automática y se omite en las interfaces que no son de escucha automática. La biblioteca en tiempo de ejecución de RPC hace su mejor esfuerzo para asegurarse de que el servidor no permite más solicitudes de llamada simultáneas que el número de llamadas especificadas en MaxCalls. El número real puede ser mayor y puede variar para cada secuencia de protocolo.

Las llamadas en otras interfaces se rigen por el valor del parámetro MaxCalls de todo el proceso especificado en la llamada de función RpcServerListen .

Si el número de llamadas simultáneas no es un problema, puede lograr un rendimiento ligeramente mejor del lado servidor especificando el valor predeterminado mediante RPC_C_LISTEN_MAX_CALLS_DEFAULT. Al hacerlo, se evita que el entorno en tiempo de ejecución rpc aplique una restricción innecesaria.

MaxRpcSize

Tamaño máximo de bloques de datos entrantes, en bytes. Este parámetro se puede usar para ayudar a evitar ataques malintencionados por denegación de servicio. Si el bloque de datos de una llamada a procedimiento remoto es mayor que MaxRpcSize, la biblioteca en tiempo de ejecución rpc rechaza la llamada y envía un error de RPC_S_ACCESS_DENIED al cliente. Si se especifica un valor de (unsigned int) –1 para este parámetro se quita el límite en el tamaño de los bloques de datos entrantes. Este parámetro no tiene ningún efecto en las llamadas realizadas a través del protocolo ncalrpc .

IfCallbackFn

Función de devolución de llamada de seguridad o NULL para ninguna devolución de llamada. Cada interfaz registrada puede tener una función de devolución de llamada diferente. Vea la sección Comentarios.

Valor devuelto

Devuelve RPC_S_OK si se realiza correctamente.

Nota Para obtener una lista de códigos de error válidos, consulte Rpc Return Values.

Comentarios

Los parámetros y efectos de la función RpcServerRegisterIf2 amplían los de la función RpcServerRegisterIf . La diferencia es la capacidad de registrar una interfaz de escucha automática y especificar una función de devolución de llamada de seguridad.

El código de la aplicación de servidor llama a RpcServerRegisterIf2 para registrar una interfaz. Para registrar una interfaz, el servidor proporciona la siguiente información:

Especificación de interfaz
La especificación de interfaz es una estructura de datos que genera el compilador MIDL.
Tipo de administrador UUID y administrador EPV
El administrador escribe UUID y el administrador EPV determinan qué rutina de administrador se ejecuta cuando un servidor recibe una solicitud de llamada a procedimiento remoto de un cliente. Para cada implementación de una interfaz ofrecida por un servidor, debe registrar un EPV de administrador independiente.

Tenga en cuenta que al especificar un UUID de tipo no nulo, el servidor también debe llamar a RpcObjectSetType para registrar objetos de este tipo no nulo.

La especificación de las marcas RPC_IF_AUTOLISTEN marca la interfaz como una interfaz de escucha automática . El tiempo de ejecución comienza a escuchar las llamadas en cuanto se registra la interfaz y deja de escuchar cuando se anula el registro de la interfaz. Una llamada a RpcServerUnregisterIf para esta interfaz espera la finalización de todas las llamadas pendientes en esta interfaz. Las llamadas a rpcServerListen y a las funciones RpcMgmtStopServerListening no afectan a la interfaz, ni a la función RpcServerUnregisterIf con IfSpec establecido en el valor NULL. Esto permite a un archivo DLL registrar interfaces RPC o quitarlas del registro sin cambiar el estado RPC de la aplicación principal.

La especificación de una función de devolución de llamada de seguridad permite a la aplicación de servidor restringir el acceso a sus interfaces de forma individual. Es decir, de forma predeterminada, la seguridad es opcional; el tiempo de ejecución del servidor enviará llamadas no seguros aunque el servidor haya llamado a la función RpcServerRegisterAuthInfo . Si el servidor solo quiere aceptar clientes autenticados, una función de devolución de llamada de interfaz debe llamar a la función RpcBindingInqAuthClient, RpcGetAuthorizationContextForClient o RpcServerInqCallAttributes para recuperar el nivel de seguridad o intentar suplantar al cliente con la función RpcImpersonateClient . También puede especificar la marca RPC_IF_ALLOW_SECURE_ONLY en las marcas de interfaz para rechazar llamadas no autenticadas.

Cuando una aplicación de servidor especifica una función de devolución de llamada de seguridad para sus interfaces, el tiempo de ejecución rpc rechaza automáticamente las llamadas sin información de autenticación a esa interfaz. Además, el tiempo de ejecución registra las interfaces que cada cliente ha usado. Cuando un cliente realiza una RPC en una interfaz que no ha usado durante la sesión de comunicación actual, la biblioteca de tiempo de ejecución rpc llama a la función de devolución de llamada de seguridad de la interfaz. Si se especifica RPC_IF_ALLOW_CALLBACKS_WITH_NO_AUTH marca, se evitará el rechazo automático de clientes no autenticados. Tenga en cuenta que las llamadas en la llamada sesión de seguridad NULL pueden tener información de autenticación, aunque procedan de clientes anónimos. Por lo tanto, la existencia de una devolución de llamada por sí sola no es suficiente para evitar que los clientes anónimos se conecten. La función de devolución de llamada de seguridad debe comprobarlo o se debe usar la marca RPC_IF_ALLOW_SECURE_ONLY. RPC_IF_ALLOW_SECURE_ONLY rechaza llamadas de sesión nulas solo en Windows XP y versiones posteriores de Windows.

Para obtener la firma de la función de devolución de llamada, consulte RPC_IF_CALLBACK_FN.

La función de devolución de llamada debe devolver RPC_S_OK, si el cliente puede llamar a métodos en esta interfaz. Cualquier otro código de retorno hará que el cliente reciba la excepción RPC_S_ACCESS_DENIED.

En algunos casos, el tiempo de ejecución de RPC puede llamar a la función de devolución de llamada de seguridad más de una vez por cliente, por interfaz. Asegúrese de que la función de devolución de llamada pueda controlar esta posibilidad.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	rpcdce.h (incluir Rpc.h)
Library	Rpcrt4.lib
Archivo DLL	Rpcrt4.dll