rpc_server_register_if(3) — Subroutines
NAME
rpc_server_register_if - Registers an interface with the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_register_if(
rpc_if_handle_t if_handle ,
uuid_t ∗mgr_type_uuid ,
rpc_mgr_epv_t mgr_epv ,
unsigned32 ∗status );
PARAMETERS
Input
if_handleAn IDL-generated data structure specifying the interface to register.
mgr_type_uuidSpecifies a type UUID to associate with the mgr_epv argument. Specifying the value NULL (or a nil UUID) registers the if_handle with a nil type UUID.
mgr_epvSpecifies the manager routines’ entry point vector. To use the IDL-generated default entry point vector, specify NULL.
Output
statusReturns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows:
rpc_s_okSuccess.
rpc_s_invalid_if_handleInvalid interface handle.
rpc_s_type_already_registered
An interface with the given type UUID already registered.
DESCRIPTION
The rpc_server_register_if routine registers a server interface with the RPC runtime. A server can register an unlimited number of interfaces. Once registered, an interface is available to clients through any binding handle of the server, provided that the binding handle is compatible for the client.
A server must provide the following information to register an interface:
•An interface specification, which is a data structure generated by the IDL compiler. The server specifies the interface specification of the interface using the if_handle argument.
•A type UUID and manager entry point vector (EPV), a data pair that determines which manager routine executes when a server receives a remote procedure call request from a client. The server specifies the type UUID and EPV using the mgr_type_uuid and mgr_epv arguments, respectively. Note that when a non-nil type UUID is specified, the server must also call the rpc_object_set_type routine to register objects of this non-nil type.
A server that only offers a single manager for an interface calls routine rpc_server_register_if once for that interface. In the simple case where the single manager’s entry point names are the same as the operation names in the IDL interface definition, the IDL-generated default manager EPV for the interface may be used. The value NULL in argument mgr_epv specifies the default manager EPV.
Note: If a server offers multiple implementations of an interface, the server code must register a separate manager entry point vector for each interface implementation.
Rules for Invoking Manager Routines
The RPC runtime dispatches an incoming remote procedure call to a manager that offers the requested RPC interface. When multiple managers are registered for an interface, the RPC runtime must select one of them. To select a manager, the RPC runtime uses the object UUID specified by the call’s binding handle.
The following table summarizes the rules applied for invoking manager routines.
Table 0-0. Rules for Invoking Manager Routines
| Object UUID of Call1 | Has Server Set Type of Object UUID?2 | Has Server Registered Type for Manager EPV?3 | Dispatching Action |
| nil | Not applicable4 | yes | Use the manager with the nil type UUID. |
| nil | Not applicable4 | no | Error (rpc_s_unknown_mgr_type). Reject the remote procedure call. |
| non-nil | yes | yes | Use the manager with the same type UUID. |
| non-nil | no | ignored | Use the manager with the nil type UUID. If no manager with the nil type UUID, error (rpc_s_unknown_mgr_type). Reject the remote procedure call. |
| non-nil | yes | no | Error (rpc_s_unknown_mgr_type). Reject the remote procedure call. |
1This is the object UUID found in a binding handle for a remote procedure.
2By calling rpc_object_set_type to specify the type UUID for an object.
3By calling rpc_server_register_if using the same type UUID.
4The nil object UUID is always automatically assigned the nil type UUID. It is illegal to specify a nil object UUID in the rpc_object_set_type routine.
For more information about registering server interfaces and invoking manager routines, see the NCS 2.0 Programmer’s Guide.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_binding_set_object(3), rpc_ep_register(3), rpc_ep_register_no_replace(3), rpc_ns_binding_export(3), rpc_object_set_type(3), rpc_server_unregister_if(3)