rpc_server_register_if(3rpc) — Subroutines
NAME
rpc_server_register_if — Registers an interface with the RPC runtime; used by server applications
Synopsis
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_uuid
Specifies a type UUID to associate with the mgr_epv parameter. 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.
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 parameter.
•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 parameters, respectively. Note that when a nonnil type UUID is specified, the server must also call the rpc_object_set_type() routine to register objects of this nonnil type.
A server that only offers a single manager for an interface calls 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 mgr_epv specifies the default manager EPV.
Note that 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.
| Rules for Invoking Manager Routines | |||
| _ | _ | _ | _ |
| Object UUID of Call 1 | Has Server Set Type of Object UUID? 2 | Has Server Set Type for Manager EPV? 3 | Dispatching Action |
| _ | _ | _ | _ |
| Nil | Not applicable 4 | Yes | Uses the manager with the nil type UUID. |
| _ | _ | _ | _ |
| Nil | Not applicable 4 | No | The RPC error (rpc_s_unknown_mgr_type). Rejects the remote procedure call. |
| Non-nil | Yes | Yes | Uses the manager with the same type UUID. |
| Rules for Invoking Manager Routines | |||
| _ | _ | _ | _ |
| Object UUID of Call 1 | Has Server Set Type of Object UUID? 2 | Has Server Registered Type for Manager EPV? 3 | Dispatching Action |
| _ | _ | _ | _ |
| Non-nil | No | Ignored | Uses the manager with the nil type UUID. If no manager with the nil type UUID, rpc_s_unknown_mgr_type. Rejects the remote procedure call. |
| _ | _ | _ | _ |
| Non-nil | Yes | No | The error (rpc_s_unknown_mgr_type). Rejects the remote procedure call. |
1 " 10 This is the object UUID found in a binding handle for a remote procedure.
2 " 10 By calling rpc_object_set_type() to specify the type UUID for an object.
3 " 10 By calling rpc_server_register_if() using the same type UUID.
4 " 10 The nil object UUID is always automatically assigned the nil type UUID. It is illegal to specify a nil object UUID in rpc_object_set_type().
For more information about registering server interfaces and invoking manager routines, refer to the OSF DCE Application Development Guide—Core Components.
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_type_already_registered
An interface with the given type of UUID is already registered.
Related Information
Functions: rpc_binding_set_object(3rpc), rpc_ep_register(3rpc), rpc_ep_register_no_replace(3rpc), rpc_ns_binding_export(3rpc), rpc_object_set_type(3rpc), rpc_server_unregister_if(3rpc).
Books: OSF DCE Application Development Guide—Core Components.