These routines obtain the actual data for items to which entries
refer (objects).
dced_object_read Reads one data item of a dced service, based on
the entry UUID
dced_object_read_all
Reads all the data of a dced service's entry list
dced_objects_release
Releases the resources allocated for data obtained
1 – dced_object_read
NAME
dced_object_read - Reads a data item of a dced service on a
specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
void **data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
entry_uuid
Specifies the UUID of the dced service's data entry associated
with the data item.
Output
data
Returns the data read. The data returned is one of the
following structures, depending on the service:
Service Data Type Returned
_____________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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
db_s_bad_index_type
db_s_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
uuid_s_bad_version
DESCRIPTION
The dced_object_read() routine reads the data for a specified entry
of a dced service. When the application is done with the data, it
should call the dced_objects_release() routine with a value of 1
for the count parameter.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab. These host services each have a
list of data entries maintained by dced. The entries do not contain
the actual data but contain the data's identity and an indicator of
the location of the data item. The hostdata service also has the
dced_hostdata_read() routine to read data, and the keytab service
has a series of routines that traverse over the keys in a key table.
(See the dced_keytab_initialize_cursor() routine.) The secval and
endpoint services do not have data items to read with this routine.
Applications can also read the data for all entries of a service
using one call to dced_objects_read_all().
Prior to reading the actual data, an application commonly obtains
the entries to read using the series of cursor routines that begin
with dced_entry_initialize_cursor().
Prior to calling the dced_object_read() 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
The following example creates a dced binding to a dced service based
on a service type and host in an rpc binding handle. The example
then obtains the service's entry list and reads the data associated
with each entry.
dced_binding_from_rpc_binding( service_type,
rpc_bh,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++) {
dced_object_read( dced_bh,
&entries.list[i].id,
&data,
&status );
.
.
.
dced_objects_release( dced_bh, 1, data, &status );
}
.
.
.
RELATED INFORMATION
Routines: dced_objects_release
dced_objects_read_all
dced_hostdata_read
dced_keytab_initialize_cursor
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2 – dced_object_read_all
NAME
dced_object_read_all - Reads all the data for a service of the
DCE Host daemon (dced) on specific host
SYNOPSIS
#include <dce/dced.h>
void dced_object_read_all( dced_binding_handle_t dced_bh,
unsigned32 *count,
void **data_list,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
Output
count
Returns the count of the number of data items read.
data_list
Returns the list of data items read. The data returned is an
array of one of the following types, depending on the service:
Service Data Type of Array Returned
______________________________________
hostdata sec_attr_t
srvrconf server_t
srvrexec server_t
keytab dced_key_list_t
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
db_s_bad_index_type
db_s_key_not_found
dce_cf_e_file_open
dce_cf_e_no_match
dce_cf_e_no_mem
dced_s_bad_binding
dced_s_need_privacy
dced_s_no_memory
dced_s_no_support
dced_s_not_found
rpc_s_binding_has_no_auth
rpc_s_invalid_binding
rpc_s_wrong_kind_of_binding
sec_acl_invalid_permission
sec_key_mgmt_e_authn_invalid
sec_key_mgmt_e_key_unavailable
sec_key_mgmt_e_unauthorized
sec_s_no_memory
uuid_s_bad_version
DESCRIPTION
The dced_object_read_all() routine reads all the data for a
specified host service on a specific host. When the application
is done with the data, it should call the dced_objects_release()
routine. Applications can also read individual data objects for a
service using the dced_object_read() routine.
The valid services for which you can read data include hostdata,
srvrconf, srvrexec, and keytab.
Prior to calling the dced_object_read_all() 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
The following example reads and displays all the data for a
particular dced service.
dced_binding_handle_t dced_bh;
dced_string_t host_service;
void *data_list;
unsigned32 count;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_object_read_all( dced_bh, &count, &data_list, &status );
display( host_service, count, &data_list ); /* app. specific */
dced_objects_release( dced_bh, count, data_list, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_objects_release
dced_object_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3 – dced_objects_release
NAME
dced_objects_release - Releases the resources allocated for data
read from a dced service
SYNOPSIS
#include <dce/dced.h>
void dced_objects_release( dced_binding_handle_t dced_bh,
unsigned32 count,
void *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for a dced service on a
specific host.
count
Specifies the number of data items previously read and now to
be released.
Input/Output
data
Specifies the data for which resources are released.
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
DESCRIPTION
The dced_objects_release() routine releases the resources allocated
when data for dced is read. Applications should call
dced_objects_release() when finished with data allocated by the
following dced API routines:
+ dced_object_read_all()
+ dced_object_read()
+ dced_hostdata_read()
If the data being released was read by using dced_object_read_all(),
the count returned from this routine is used as input to the
dced_objects_release() routine. If the data being released was read
by using dced_object_read() or dced_hostdata_read(), the count value
required as input for the dced_objects_release() routine is 1.
EXAMPLES
In the following example, a binding is created to a dced service
on some host for a service that stores data, and the service's
entry list is obtained. For each entry, the data is read,
displayed, and released.
dced_binding_handle_t dced_bh;
dced_entry_list_t entries;
unsigned32 i;
void *data;
error_status_t status;
dced_binding_create( host_service,
dced_c_binding_syntax_default,
&dced_bh,
&status );
dced_list_get( dced_bh, &entries, &status );
for(i=0; i<entries.count; i++) {
dced_object_read( dced_bh,
&(entries.list[i].id),
&data,
&status );
display( host_service, 1, &data ); /* app. specific */
dced_objects_release( dced_bh, 1, data, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_object_read_all
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.