Función RpcServerRegisterIfEx (rpcdce.h)

Artículo
03/15/2023

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

Sintaxis

RPC_STATUS RpcServerRegisterIfEx(
  RPC_IF_HANDLE      IfSpec,
  UUID               *MgrTypeUuid,
  RPC_MGR_EPV        *MgrEpv,
  unsigned int       Flags,
  unsigned int       MaxCalls,
  RPC_IF_CALLBACK_FN *IfCallback
);

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 . Al especificar 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 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, consulte Marcas de registro de interfaz.

MaxCalls

Número máximo de solicitudes simultáneas de llamada a procedimiento remoto que el servidor puede aceptar en una interfaz de escucha automática. Los parámetros MaxCalls solo se aplican en una interfaz de escucha automática y se omiten en las interfaces que no son de escucha automática. La biblioteca en tiempo de ejecución 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.

IfCallback

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. Consulte Comentarios para obtener más detalles.

Valor devuelto

Devuelve RPC_S_OK tras el éxito.

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

Comentarios

Los parámetros y efectos de RpcServerRegisterIfEx suumen los de 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 aplicación de servidor llama a RpcServerRegisterIfEx 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 que ofrece un servidor, debe registrar un EPV de administrador independiente.

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

Especificar las marcas de 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 esperará la finalización de todas las llamadas pendientes en esta interfaz. Las llamadas a RpcServerListen y RpcMgmtStopServerListening no afectarán a la interfaz, ni a una llamada a RpcServerUnregisterIf con IfSpec == NULL. Esto permite a un archivo DLL registrar interfaces RPC o quitarlas del registro sin cambiar el estado RPC de la aplicación principal.

Especificar una función de devolución de llamada de seguridad permite que la aplicación de servidor restrinja el acceso a sus interfaces por cliente. Recuerde que, de forma predeterminada, la seguridad es opcional; El tiempo de ejecución del servidor enviará llamadas no seguros incluso si el servidor ha llamado 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 o RpcGetAuthorizationContextForClient para recuperar el nivel de seguridad o intentar suplantar al cliente con RpcImpersonateClient. También puede especificar la marca RPC_IF_ALLOW_SECURE_ONLY en las marcas de interfaz.

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 no autenticadas a esa interfaz. Además, el tiempo de ejecución registra las interfaces que ha usado cada cliente. Cuando un cliente realiza una RPC en una interfaz que no se ha usado durante la sesión de comunicación actual, la biblioteca en tiempo de ejecución rpc llamará 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.

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 y por interfaz. Asegúrese de que la función de devolución de llamada puede controlar esta posibilidad.

Requisitos

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