NAME rpc_ep_register - Adds to, or replaces, server address information in the local endpoint map Used by server applications. SYNOPSIS #include <dce/rpc.h> void rpc_ep_register( rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned_char_t *annotation, unsigned32 *status ); PARAMETERS Input if_handle Specifies an interface specification to register with the local endpoint map. binding_vec Specifies a vector of binding handles over which the server can receive remote procedure calls. object_uuid_vec Specifies a vector of object UUIDs that the server offers. The server application constructs this vector. Supply the value NULL to indicate there are no object UUIDs to register. annotation Defines a character string comment applied to each cross product element added to the local endpoint map. The string can be up to 64 characters long, including the NULL terminating character. Specify NULL or the string \0 if there is no annotation string. The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements. Output status Returns 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_ok Success. ept_s_cant_access Error reading endpoint database. ept_s_cant_create Error creating endpoint database. ept_s_cant_perform_op Cannot perform requested operation. ept_s_database_invalid Endpoint map database invalid. ept_s_invalid_entry Invalid database entry. ept_s_update_failed Update failed. rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_no_bindings No bindings. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ep_register() routine adds elements to, or replaces elements in, the local host's endpoint map. Each element in the local endpoint map logically contains the following: + Interface ID, consisting of an interface UUID and versions (major and minor) + Binding information + Object UUID (optional) + Annotation (optional) A server uses this routine, instead of rpc_ep_register_no_replace(), when only a single instance of the server runs on the server's host. Use this routine if, at any time, no more than one server instance offers the same interface UUID, object UUID, and protocol sequence. When local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without calling rpc_ep_unregister(). Periodically the DCE Host Daemon identifies these obsolete elements and removes them. However, during the time between these removals the obsolete elements increase the chance that a client will receive endpoints to nonexistent servers. The client then wastes time trying to communicate with these servers before obtaining another endpoint. Using this routine to replace any existing local endpoint map elements reduces the chance that a client will receive the endpoint of a nonexistent server instance. Suppose an existing element in the local endpoint map matches the interface UUID, binding information exclusive of the endpoint, and object UUID of an element this routine provides. The routine changes the endpoint map according to the elements' interface major and minor version numbers, as shown in the following table: Existing Element Relationship Provided Element Routine's Action ______________________________________________________________________ Major version # Not equal to Major version # Ignores minor ver- sion number rela- tionship and adds a new endpoint map element. The existing element remains unchanged. Major version # Equal to Major version # Acts according to the minor version number relation- ship. Minor version # Equal to Minor version # Replaces the end- point of the existing element based on the pro- vided information. Minor version # Less than Minor version # Replaces the existing element based on the pro- vided information. Minor version # Greater than Minor version # Ignores the pro- vided information. The existing ele- ment remains unchanged. For example, suppose under these circumstances that the existing interface version number is 1.3 (major.minor) and the provided version number is 2.0. The routine adds a new endpoint map element with interface version number 2.0 and does not change the element with version number 1.3. However, if the existing interface version number is 1.5 and the provided version number is 1.4, the routine does not change the endpoint map. A server program calls this routine to register endpoints that have been specified by calling any of the following routines: + rpc_server_use_all_protseqs() + rpc_server_use_protseq() + rpc_server_use_protseq_ep() A server that calls only the rpc_server_use_all_protseqs_if() or rpc_server_use_protseq_if() routines does not need to call this routine. In such cases, the client's runtime uses an endpoint from the client's interface specification to fill in a partially bound binding handle. However, it is recommended that you also register well-known endpoints that the server specifies (registering endpoints from interface definitions is unnecessary). If the server also exports to the name service database, the server calls this routine with the same if_handle, binding_vec and object_uuid_vec parameters as the server uses when calling the rpc_ns_binding_export() routine. The rpc_ep_register() routine communicates with the DCE Host Daemon (dced), which in turn communicates with the local endpoint map. The routine communicates using one of the protocol sequences specified in one of the binding handles in binding_vec. Attempting to register a binding that specifies a protocol sequence that the DCE Host daemon is not listening on results in the failure of rpc_ep_register(). The routine indicates this failure by placing the value rpc_s_comm_failure into status. For information about how the endpoint map service selects an element for an interface ID and an object UUID, see the RPC information in the OSF DCE Application Development Guide. This guide explains how the endpoint map service searches for the endpoint of a server that is compatible with a client. If the client supplies a non-nil object UUID that is not in the endpoint map, or the client supplies a nil object UUID, the search can succeed, but only if the server has registered a nil object UUID using the rpc_ep_register() or rpc_ep_register_no_replace() routines. The object_uuid_vec parameter can contain both nil and non-nil object UUIDs for the routine to place into endpoint map elements. For an explanation of how a server can establish a client/server relationship without using the local endpoint map, see the explanation of a string binding in the rpc_intro reference page. This routine creates a cross product from the if_handle, binding_vec and object_uuid_vec parameters, and adds each element in the cross product as a separate registration in the local endpoint map. If you supply NULL to object_uuid_vec, the corresponding elements in the cross product contain a nil object UUID. For example, suppose that if_handle has the value ifhand, binding_vec has the values b1, b2, b3, and object_uuid_vec has the values u1, u2, u3, u4.The resulting 12 elements in the cross product are as follows: (ifhand,b1,u1) (ifhand,b1,u2) (ifhand,b1,u3) (ifhand,b1,u4) (ifhand,b2,u1) (ifhand,b2,u2) (ifhand,b2,u3) (ifhand,b2,u4) (ifhand,b3,u1) (ifhand,b3,u2) (ifhand,b3,u3) (ifhand,b3,u4) (An annotation string is part of each of these 12 elements.) RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register_no_replace rpc_ep_resolve_binding rpc_ep_unregister rpc_mgmt_ep_unregister rpc_ns_binding_export rpc_server_inq_bindings rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if Books: OSF DCE Application Development Guide.