NAME
dce_server_intro - Introduction to the DCE server routines
DESCRIPTION
The routines described on this reference page are used by servers to
register themselves with DCE. This includes registering with the RPC
runtime, the local endpoint mapper, and the namespace. Routines are
also available to set up DCE security so that servers can receive and
invoke authenticated RPCs.
THE DCE SERVER ROUTINES
The server routines are as follows, listed in alphabetical order:
dce_server_disable_service()
Unregisters an individual interface of a DCE
server from the RPC runtime, and marks the
server's endpoints as disabled in the dced's
endpoint mapper service.
dce_server_enable_service()
Registers an individual interface (application
service) of a DCE server with the RPC runtime,
and marks the server's endpoints as enabled in
the dced's endpoint mapper service.
dce_server_inq_attr()
Obtains application-specific attribute data
from the dced server configuration data.
dce_server_inq_server()
Obtains the server configuration data dced
used to start the server.
dce_server_inq_uuids()
Obtains the UUIDs that dced used in its srvrconf
and srvrexec facilities to identify the server's
configuration and execution data.
dce_server_register()
Registers a DCE server by establishing a server's
binding information, registering its services
(represented by interface IDs) with the RPC
runtime, and entering its endpoints in the dced's
endpoint mapper service.
dce_server_sec_begin()
Prepares a server to receive and generate
authenticated RPCs.
dce_server_sec_done()
Releases the resources previously set up by a
call to dce_server_sec_begin().
dce_server_unregister()
Unregisters a DCE server by unregistering a
servers services (interfaces) from the RPC
runtime, and removing the server's endpoints
from the dced's endpoint mapper service.
dce_server_use_protseq()
Registers a protocol sequence to use for the
server.
DATA TYPES AND STRUCTURES
dce_server_handle_t An opaque data structure containing information
the runtime uses to establish the server with DCE.
dce_server_register_data_t
A structure that contains an interface handle
(generated by IDL), a default EPV, and a count
and array of dce_server_type_ts for services that
use RPC object types.
dce_server_type_t A structure containing a manager type UUID and an
RPC entry-point vector (EPV) that specified which
routines implement the IDL interface for the
specific type.
server_t See dced_intro for a complete description of
server_t.
FILES
dce/dced.h
dce/dced_base.idl
RELATED INFORMATION
BOOKS: OSF DCE Application Development Guide
1 – dce_server_disable_service
NAME
dce_server_disable_service - Disables an individual service of a
server
SYNOPSIS
#include <dce/dced.h>
void dce_server_disable_service( dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
interface
Specifies an opaque variable containing information the runtime
uses to access interface specification data.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_disable_service() routine disables an individual
service that a server provides by unregistering the service's
interface from the RPC runtime and marking the server's endpoints
as disabled in the local dced's endpoint mapper service.
For dced to recognize all of a server's services, a server should
register all its application services using the dce_server_register()
routine. If it later becomes necessary for the server to disable an
interface, it can use the dce_server_disable_service() routine rather
than unregistering the entire server.
RELATED INFORMATION
Routines: rpc_intro
dce_server_enable_service
dce_server_register
Books: OSF DCE Application Development Guide
2 – dce_server_enable_service
NAME
dce_server_enable_service - Enables an individual service for a
server
SYNOPSIS
#include <dce/dced.h>
void dce_server_enable_service( dce_server_handle_t server_handle,
rpc_if_handle_t interface,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
interface
Specifies an opaque variable containing information the runtime
uses to access interface specification data.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The
only status code is error_status_ok.
DESCRIPTION
The dce_server_enable_service() routine enables an individual
service that a server provides by registering the service's
interface with the RPC runtime, and registering the endpoints in
the endpoint map. If the dce_server_c_no_endpoints flag was set
with the dce_server_register() call prior to callibng this routine,
the endpoints are not registered in the endpoint map.
A server commonly registers all its services with DCE at once by
using the dce_server_register() routine. If necessary, a server
can use the dce_server_disable_service() routine to disable
individual services and then reenable them by using
dce_server_enable_service(). However, suppose a server needs its
services registered in a certain order, or it require application-
specific activities between the registration of services. If a
server requires this kind of control as services are registered,
you can set the server->services.list[i].flags field of the
server_t structure to service_c_disabled for individual services
prior to calling dce_server_register(). Then, the server can call
dce_server_enable_service() for each service when needed.
RELATED INFORMATION
Routines: dce_server_disable_service
dce_server_register
Books: OSF DCE Application Development Guide
3 – dce_server_inq_attr
NAME
dce_server_inq_attr - Obtains from dced the value of an attribute
known to the server
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_attr( uuid_t *attribute_uuid,
sec_attr_t *value,
error_status_t *status );
PARAMETERS
Input
attribute_uuid
The UUID dced uses to identify an attribute.
Output
value
Returns the attribute.
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 are:
error_status_ok
dced_s_server_attr_not_found
dced_s_not_started_by_dced
DESCRIPTION
The dce_server_inq_attr() routine obtains an attribute from the
environment created by dced when it started the server. Each
server maintains among other things, a list of attributes that
are used to describe application-specific behavior.
RELATED INFORMATION
Routines: sec_intro
dced_intro
dce_server_inq_uuids
dce_server_inq_server
Books: OSF DCE Application Development Guide
4 – dce_server_inq_server
NAME
dce_server_inq_server - Obtains the server configuration data dced
used to start the server
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_server( server_t **server,
error_status_t *status );
PARAMETERS
Output
server
Returns the structure that describes the server's configuration.
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 are:
error_status_ok
dced_s_not_started_by_dced
dced_s_data_unavailable
DESCRIPTION
The dce_server_inq_server() routine obtains the server configuration
data (srvrconf) maintained by dced and used by dced to start the
server. This routine is commonly called prior to registering the
server to obtain the server data used as input to
dce_server_register().
RELATED INFORMATION
Routines: dced_intro
dce_server_register
Books: OSF DCE Application Development Guide
5 – dce_server_inq_uuids
NAME
dce_server_inq_uuids - Obtains the UUIDs that dced associates with
the server's configuration and execution data
SYNOPSIS
#include <dce/dced.h>
void dce_server_inq_uuids( uuid_t *conf_uuid,
uuid_t *exec_uuid,
error_status_t *status );
PARAMETERS
Output
conf_uuid
Returns the UUID that dced uses to identify the server's
configuration data. If a NULL value is input, no value is
returned.
exec_uuid
Returns the UUID that dced uses to identify the executing server.
If a NULL value is input, no value is returned.
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 are:
error_status_ok
dced_s_not_started_by_dced
DESCRIPTION
The dce_server_inq_uuids() routine obtains the UUIDs that dced uses
in its srvrconf and srvrexec services to identify the server's
configuration and execution data. The server can then use dced API
routines to access the data and perform other server management
functions.
RELATED INFORMATION
Routines: dced_intro
dce_server_inq_server
dced_API
Books: OSF DCE Application Development Guide
6 – dce_server_register
NAME
dce_server_register - Registers a server with DCE
SYNOPSIS
#include <dce/dced.h>
void dce_server_register( unsigned32 flags,
server_t *server,
dce_server_register_data_t *data,
dce_server_handle_t *server_handle,
error_status_t *status );
PARAMETERS
Input
flags
Specifies options for server registration. Combinations of the
following values may be used:
dce_server_c_no_protseqs
dce_server_c_no_endpoints
dce_server_c_ns_export
server
Specifies the server data, commonly obtained from dced by calling
dce_server_inq_server(). The server_t structure is described in
sec_intro.
data
Specifies the array of data structures that contain the
additional information required for the server to service
requests for specific remote procedures. Each structure of
the array includes:
+ An interface handle (ifhandle) of type rpc_if_handle_t
+ An entry point vector (epv) of type rpc_mgr_epv_t
+ A number (num_types) of type unsigned32 representing the
number in the following array
+ An array of server types (types) of type dce_server_type_t
The dce_server_type_t structure contains a UUID (type) of type uuid_t
representing the object type, and a manager entry point vector (epv)
of type rpc_mgr_epv_t representing the set of procedures implemented
for the object type.
Output
server_handle
Returns a server handle, which is a pointer to an opaque data
structure containing information about the server.
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 are:
error_status_ok
rpc_s_no_memory
DESCRIPTION
By default, the dce_server_register() routine registers a DCE server
by establishing a server's binding information for all valid protocol
sequences, registering all the servers services with the RPC runtime,
and entering the server's endpoints in dced's endpoint mapper service.
Prior to calling the dce_server_register() routine, the server
obtains the server configuration data from dced by calling
dce_server_inq_server(). The server must also set up an array of
registration data, where the size of the array represents all the
server's services that are currently registered in the server
configuration data of dced. (server->services.count). If the
memory for the array is dynamically allocated, it must not be freed
until after the corresponding dce_server_unregister() routine is
called.
You can modify the behavior of dce_server_register() Depending on
the values of the flags parameter. If the flag has the value
dce_server_c_ns_export, the the binding information is also exported
to the namespace. The namespace entry is determined for each service
by the server->services.list[i].entryname parameter. If this parameter
has no value, the default value for the entire server is used
(server->entryname). If the flag has the value
dce_server_c_no_endpoints, the binding information is not registered
with the endpoint map. Your application can use rpc_ep_register() to
register specific binding information. If the flag has the value
dce_server_c_no_protseqs, specific protocol sequences are used rather
than all valid protocol sequences. Use of this flag requires that
the server first call dce_server_use_protseq() at least once for a
valid protocol sequence.
RELATED INFORMATION
Routines: dced_intro
dce_server_inq_server
dce_server_unregister
rpc_server_listen
dce_server_sec_begin
Books: OSF DCE Application Development Guide
7 – dce_server_sec_begin
NAME
dce_server_sec_begin - Establishes a server to receive fully
authenticated remote procedure calls (RPCs)
and to also act as a client to do authenti-
cated RPCs
SYNOPSIS
#include <dce/dced.h>
void dce_server_sec_begin( unsigned32 flags,
error_status_t *status );
PARAMETERS
Input
flags
Flags are set to manage keys and setup a login context.
Valid values include the following:
dce_server_c_manage_key
dce_server_c_login
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 are:
error_status_ok
dced_s_need_one_server_prin
dced_s_not_started_by_dced
dced_s_no_server_keyfile
dced_s_cannot_create_key_mgmt_thr
dced_s_cannot_detach_key_mgmt_thr
DESCRIPTION
The dce_server_sec_begin() routine prepares a server to receive
authenticated RPCs. It also sets up all that is required for the
application, when behaving as a client to other servers, to do
authenticated RPCs as a client. When authentication is required,
this call must preceed all other RPC and DCE server initialization
calls, including dce_server_register(). When your application is
finished listening for RPCs, it should call the dce_server_sec_done()
routine.
RELATED INFORMATION
Routines: dce_server_register
rpc_server_listen
dce_server_sec_done
Books: OSF DCE Application Development Guide
8 – dce_server_sec_done
NAME
dce_server_sec_done - Releases resources established for a server
to receive (and when acting as a client, to
send) fully authenticated remote procedure
calls (RPCs)
SYNOPSIS
#include <dce/dced.h>
void dce_server_sec_done( error_status_t *status );
PARAMETERS
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_sec_done() routine releases the resources
previously set up by a call to dce_server_sec_begin(). The
dce_server_sec_begin() routine sets all that is needed for a
server to receive authenticated RPCs and it also sets up all that
is required for the application to do authenticated RPCs as a
client. If this routine is used, it must follow all other server
DCE and RPC initialization and cleanup calls.
RELATED INFORMATION
Routines: dce_server_sec_begin
rpc_server_listen
Books: OSF DCE Application Development Guide
9 – dce_server_unregister
NAME
dce_server_unregister - Unregisters a DCE server
SYNOPSIS
#include <dce/dced.h>
void dce_server_unregister( dce_server_handle_t *server_handle,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle returned by dce_server_register().
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_unregister() routine unregisters a DCE server by
unregistering a servers services (interfaces) from the RPC runtime.
When a server has stopped listening for remote procedure calls, it
should call this routine.
The flags set with the corresponding dce_server_register() routine
are part of the server handle's information used to determine what
action to take or not take. These actions include removing the
server's endpoints from the dced's endpoint mapper service and
unexporting binding information from the namespace.
Use the dce_server_disable_service() routine to disable specific
application services rather than unregistering the whole server.
RELATED INFORMATION
Routines: dce_server_register
rpc_server_listen
dce_server_disable_service
Books: OSF DCE Application Development Guide
10 – dce_server_use_protseq
NAME
dce_server_use_protseq - Tells DCE to use the specified protocol
sequence for receiving remote procedure
calls
Used by server applications.
SYNOPSIS
#include <dce/dced.h>
void dce_server_use_protseq( dce_server_handle_t server_handle,
unsigned char *protseq,
error_status_t *status );
PARAMETERS
Input
server_handle
An opaque handle. Use the value of NULL.
protseq
Specifies a string identifier for the protocol sequence to
register with the RPC runtime. (For a list of string
identifiers, see the table of valid protocol sequences in the
rpc_intro reference page.)
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully. The only
status code is error_status_ok.
DESCRIPTION
The dce_server_use_protseq() routine registers an individual
protocol sequence with DCE. Typical servers use all valid protocol
sequences, the default behavior for the dce_server_register() call,
and so most servers do not need to call this dce_server_use_protseq()
routine. However, this routine may be called prior to
dce_server_register(), to restrict the protocol sequences used. A
server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can
call this routine multiple times to register additional protocol
sequences.
RELATED INFORMATION
Routines: rpc_intro
dce_server_register
rpc_server_use_protseq
Books: OSF DCE Application Development Guide