NAME

rpc_server_register_if- registers interface/type UUID/EPV associations with the RPC run-time system

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_handle

Specifies the interface to register.

mgr_type_uuid

Specifies 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_epv

Specifies the manager routine's entry point vector. Specifying NULL causes the routine to supply a default entry point vector.

Output

status

Returns the status code from this routine. The status code indicates whether the routine completed successfully, or if not, why not.

Possible status codes and their meanings include:

rpc_s_ok

Success.

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 run-time system. 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 client supports the protocols specified in the binding handle.

A server must provide the following information to register an interface with rpc_server_register_if():

• an interface specification; the server specifies this using the if_handle argument

• a type UUID and manager entry point vector (EPV) pair, using the mgr_type_uuid and mgr_epv arguments, respectively; this data pair identifies a manager to handle calls on the interface.

A server may register more than one manager per interface. To do so, the server calls rpc_server_register_if() at least once for each manager, specifying a different type UUID/manager EPV data pair each time.

The type UUID/manager EPV data pairs registered by this routine are used by the run-time system to determine which manager is invoked when a server receives a remote procedure call request from a client. When an RPC request is received on an interface, the RPC run-time system matches the object UUID of the call to one of the registered type UUID/manager EPV pairs and dispatches the call through the selected EPV to the appropriate manager routines.

By default, a nil object UUID matches a nil type UUID. To enable any other matches, the server must establish a mapping of object UUIDs to type UUIDs by calling the routine rpc_object_set_type(). The server must call rpc_object_set_type() at least once for each non-nil type UUID it has registered in order to make that type UUID available for dispatching calls.

Note:

The mapping of object UUIDs to type UUIDs applies to all registered interfaces. If a non-nil type UUID has already been set for one interface, it is not necessary to call rpc_object_set_type again when that type UUID is registered for a different interface.

In an interface, one manager EPV may be registered with a nil type UUID. As the table below shows, this manager, by default, receives calls with object UUIDs that do not match another type UUID. Note that rpc_object_set_type() cannot be used to set the nil object UUID to match any other type UUID. However, a non-nil object UUID may be mapped to the nil type UUID. (See tagmref_rpc_object_set_type for further information on the object UUID to type UUID mapping.)

More than one type UUID may be registered for each manager EPV on consecutive calls to rpc_server_register_if(), allowing calls whose object UUIDs match different type UUIDs to be dispatched to the same manager. However, only one manager EPV for an interface may be registered per type UUID. When an interface has been registered with a given type UUID, attempting to register it with the same type UUID results in the error rpc_s_type_already_registered.

The following table summarises the rules used by the RPC run-time system for invoking manager routines.

	Has Server	Has Server
Object	Set Type	Registered Type
UUID	of Object	for Manager	Dispatching
of Call1	UUID?2	EPV?3	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.

1. This is the object UUID found in a binding handle for a remote procedure.

2. The server specifies the type UUID for an object by calling rpc_object_set_type().

3. The server registers the type for the manager EPV by calling rpc_server_register_if() using the same type UUID.

4. The 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.

Specifying the Manager EPV

To use the implementation-provided default manager EPV, a server can specify the value NULL for the mgr_epv argument to rpc_server_register_if(). A server that registers only one manager for an interface, and that wishes to use the default manager EPV needs to call rpc_server_register_if() only once, specifying the value NULL for the mgr_epv argument.

To use a non-default manager EPV, the server initialises a variable of the following type for each implementation of the interface:

 

<if-name>_v

To register such a server supplied EPV using rpc_server_register_if(), the server passes a pointer to it as the mgr_epv argument.

When a server registers only one manager for an interface, it can use either the default manager EPV or it can supply one. When a server registers more than one manager for an interface, it can use the default manager EPV for one of the managers, but it must supply manager EPVs for all the other managers. The server may supply manager EPVs for all managers.

Specifying the Type UUID

A server may specify a nil type UUID for one of the manager EPVs registered. Calls are dispatched to a manager registered with the nil type UUID in two circumstances:

• when the call object UUID is nil

• when the call object UUID is non-nil and no type UUID has been set for the object UUID.

When a server registers only one manager for an interface, it can use either a nil or non-nil value. When a server registers more than one manager for an interface, it can use the nil type UUID for one of the manager EPVs. The server must supply distinct non-nil type UUIDs for all other manager EPVs registered. The server may supply non-nil type UUIDs for all manager EPVs registered.

The server may not specify the same type UUID for more than one manager EPV. The server may, however, specify more than one type UUID per manager EPV. To do so, the server calls rpc_server_register_if() more than once, each time specifying a type UUID/manager EPV pair with the same manager EPV and a different type UUID. This permits calls with object UUIDs that match different type UUIDs to be handled by the same manager.

When a server registers the nil type UUID, and does not make any calls to rpc_object_set_type(), all calls, regardless of object UUID, are dispatched to the manager EPV registered with the nil type UUID. In the simplest case, a server calls rpc_server_register_if with a NULL mgr_epv argument, specifying the default manager EPV, and a nil mgr_type_uuid argument. If such a server does not call rpc_object_set_type(), all calls will be dispatched to the default manager.

RETURN VALUE

None.

SEE ALSO

rpc_binding_from_string_binding()
rpc_binding_set_object()
rpc_ep_register()
rpc_ep_register_no_replace()
rpc_ns_binding_export()
rpc_ns_binding_import_begin()
rpc_ns_binding_lookup_begin()
rpc_object_set_type()
rpc_server_unregister_if().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.