A binding must be established to a dced service on a particular host
before you can use any other dced routines. The resources of the
dced binding should also be released when an application is finished
with the service.
dced_binding_create Establishes a dced binding to a host service
dced_binding_from_rpc_binding
Establishes a dced binding to a dced service on
the host specified in an already-established RPC
binding handle to any server
dced_binding_set_auth_info
Sets authentication, authorization, and
protection level information for a dced binding
handle
dced_binding_free Releases the resources of a dced binding handle
1 – dced_binding_create
NAME
dced_binding_create - Establishes a dced binding to one of the
host services of a remote (or the local) dced.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_create( dced_string_t service,
unsigned32 binding_flags,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A character string that specifies a host daemon service name
and an optional remote host. A service name is specified with
one of the following: hostdata, srvrconf, srvrexec, secval, or
keytab. The format of a complete service and host specification
is one of the following:
service_name
A service at the local host. Pre-existing defined
values include:
dced_c_service_hostdata
dced_c_service_srvrconf
dced_c_service_srvrexec
dced_c_service_secval
dced_c_service_keytab
service_name@hosts/host_name
A service at a host anywhere in the local namespace.
/.:/hosts/host_name/config/service_name
A complete specification for service_name@host, where
the host is anywhere in the local namespace.
/.../cell/hosts/host_name/config/service_name
A service at a host anywhere in the global namespace.
binding_flags
Currently, the only valid flag value is
dced_c_binding_syntax_default.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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
dce_cf_e_no_mem
dced_s_invalid_arg
dced_s_no_memory
dced_s_unknown_service
rpc_s_entry_not_found
rpc_s_incomplete_name
rpc_s_invalid_object
rpc_s_name_service_unavailable
rpc_s_no_memory
rpc_s_no_more_bindings
rpc_s_no_ns_permission
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to them. The host services include the
following:
+ Endpoint Mapper
+ Host Data Management (hostdata)
+ Server Management: Including Server Configuration (srvrconf)
and Server Execution (srvrexec)
+ Security Validation (secval)
+ Key Table Management (keytab)
The dced_binding_create() routine establishes a dced binding to a
dced service and it (or dced_binding_from_rpc_binding()) must be the
first dced API routine called before an application can access one
of the host services with other dced API routines. When an
application is finished with the service, it should call the
dced_binding_free() routine to free resources. To establish a dced
binding to your local host's dced, you can use the service name by
itself, and do not need to specify a host.
To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin()
and associated routines.
EXAMPLES
This example establishes a dced binding to the server configuration
service on the host patrick.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create("srvrconf@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status);
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2 – dced_binding_from_rpc_binding
NAME
dced_binding_from_rpc_binding - Establishes a dced binding to one
of the host services on the host
specified in an existing RPC binding
handle.
SYNOPSIS
#include <dce/dced.h>
void dced_binding_from_rpc_binding( dced_service_type_t service,
handle_t rpc_bh,
dced_binding_handle_t *dced_bh,
error_status_t *status );
PARAMETERS
Input
service
A variable that specifies one of the host services. A valid
variable name includes one of the following:
dced_e_service_type_hostdata
dced_e_service_type_srvrconf
dced_e_service_type_srvrexec
dced_e_service_type_secval
dced_e_service_type_keytab
rpc_bh
An RPC binding handle to some server.
Output
dced_bh
Returns a dced binding handle which is a pointer to an opaque
data structure containing information about an RPC binding, the
host, the host service, and a local cache.
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_no_memory
dced_s_unknown_service
ept_s_cant_perform_op
ept_s_database_invalid
ept_s_invalid_context
ept_s_invalid_entry
rpc_s_comm_failure
rpc_s_fault_context_mismatch
rpc_s_invalid_arg
rpc_s_invalid_binding
rpc_s_no_more_elements
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced on each DCE host maintains the host services and provides
a remote interface to the services. The
dced_binding_from_rpc_binding() routine establishes a dced binding
to a dced service, and it (or dced_binding_create()) must be the
first dced API routine called before an application can access one
of the host services with other dced routines. When an application
is finished with the service, it should call the dced_binding_free()
routine to free resources.
Prior to using the RPC binding in this routine, make a copy of the
binding by using the rpc_binding_copy() routine. This is necessary
if the application needs to continue using the RPC binding because
otherwise the dced binding takes over the RPC binding.
The RPC binding may be obtained from a call to specific RPC
runtime routines such as rpc_binding_from_string_binding,
rpc_ns_binding_import_next, or rpc_ns_binding_lookup_next.
EXAMPLES
This example obtains an RPC binding from a string binding,
and it later makes a copy of the RPC binding for use in the
dced_binding_from_rpc_binding() call.
handle_t rpc_bh, binding_handle;
dced_binding_handle_t dced_bh;
dced_service_type_t service_type;
error_status_t status;
unsigned_char_t string_binding[STRINGLEN];
.
.
.
rpc_binding_from_string_binding( string_binding,
&binding_handle,
&status );
.
.
.
rpc_binding_copy( binding_handle, &rpc_bh, &status );
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
.
. /* Other routines including dced API routines. */
.
dced_binding_free(dced_bh, &status);
RELATED INFORMATION
Routines: dced_binding_free
dced_binding_create
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_binding_from_string_binding
rpc_binding_copy
Books: OSF DCE Application Development Guide.
3 – dced_binding_set_auth_info
NAME
dced_binding_set_auth_info - Sets authentication and authorization
information for a dced binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_set_auth_info(
dced_binding_handle_t dced_bh,
unsigned32 protect_level,
unsigned32 authn_service,
rpc_auth_identity_handle_t authn_identity,
unsigned32 authz_service,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for which to set the
authentication and authorization information.
protect_level
Specifies the protection level for dced API calls that will
use the dced binding handle dced_bh.
authn_service
Specifies the authentication service to use for dced API calls
that will use the dced binding handle dced_bh.
authn_identity
Specifies a handle for the data structure that contains the
calling application's authentication and authorization
credentials appropriate for the selected authn_service and
authz_service services. Specify NULL to use the default
security login context for the current address space.
authz_service
Specifies the authorization service to be implemented by dced
for the host service accessed.
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_bad_binding
dced_s_no_support
ept_s_not_registered
rpc_s_authn_authz_mismatch
rpc_s_binding_incomplete
rpc_s_comm_failure
rpc_s_invalid_binding
rpc_s_mgmt_op_disallowed
rpc_s_rpcd_comm_failure
rpc_s_unknown_authn_service
rpc_s_unsupported_protect_level
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_set_auth_info() routine sets up the dced binding
handle so it can be used for authenticated calls that include
authorization information. The rpc_binding_set_auth_info routine
performs in the same way as this one. See it for details of the
parameters and values. Prior to calling this routine, the
application must have established a valid dced binding handle by
calling either the dced_binding_create() or
dced_binding_from_rpc_binding() routine.
EXAMPLES
This example establishes a dced binding to a host's key table
service, and then it calls dced_binding_set_auth_info() so that
the application is authorized to access remote key tables by using
additional calls to the key table service.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_binding_create( (dced_string_t)"keytab@hosts/patrick",
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_binding_set_auth_info( dced_bh,
rpc_c_protect_level_default,
rpc_c_authn_pkt_privacy,
NULL,
rpc_c_authz_dce,
&status );
.
. /* Other routines including dced API routines. */
.
RELATED INFORMATION
Routines rpc_binding_set_auth_info
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4 – dced_binding_free
NAME
dced_binding_free - Releases the resources associated with a dced
binding handle
SYNOPSIS
#include <dce/dced.h>
void dced_binding_free( dced_binding_handle_t dced_bh,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies a dced binding handle to free for a dced service on a
specific host.
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
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
DESCRIPTION
The dced_binding_free() routine frees resources used by a dced
binding handle and referenced information. Use this routine when
your application is finished with a host service to break the
communication between your application and the dced. The dced
binding handle and referenced information is created with the
dced_binding_create() or dced_binding_from_rpc_binding() routine.
RELATED INFORMATION
Routines: dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.