dced_hostdata_create
Creates a hostdata item and the associated entry
dced_hostdata_read Reads a hostdata item
dced_hostdata_write Replaces an existing hostdata item
dced_hostdata_delete
Deletes a hostdata item from a specific host and
removes the associated entry
1 – dced_hostdata_create
NAME
dced_hostdata_create - Creates a hostdata item and the associated
entry in dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_create( dced_binding_handle_t dced_bh,
dced_entry_t *entry,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the host data service
on a specific host.
Input/Output
entry
Specifies the hostdata entry to create. You supply a name
(entry->name), description (entry->description), and file
name (entry->storage_tag), in the form of dced strings. You
can supply a UUID (entry->id) for dced to use or you can use
a NULL value and dced will generate a new UUID for the entry.
Input
data
Specifies the data created and written to a file on the host.
The dced_attr_list_t consists of a count of the number of
attributes, and an array of attributes of type sec_attr_t.
The reference OSF implementation has one attribute for a
hostdata item (file contents). However some vendors may
provide multiple attributes.
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
db_s_key_not_found
db_s_readonly
db_s_store_failed
dced_s_already_exists
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_import_already_exists
dced_s_unknown_attr_type
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_create() routine creates a new host data item in
a file on the host to which the dced binding handle refers, and it
generates the associated hostdata entry in the host's dced.
If data that you want to add to the host data service already exists
on the host (in a file), you can add it to the service by calling
dced_entry_add(), which only creates the new data entry for dced.
Prior to calling the dced_hostdata_create() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
EXAMPLES
The following example creates a binding to the host data service
on the local host, creates the entry data, and fills in the data
structure for one attribute to a hypothetical printer configuration.
The attribute represents a plain-text file containing one string of
data.
dced_binding_handle_t dced_bh;
error_status_t status;
dced_entry_t entry;
dced_attr_list_t data;
int num_strings, str_size;
sec_attr_enc_str_array_t *attr_array;
dced_binding_create( dced_c_service_hostdata,
dced_c_binding_syntax_default,
&dced_bh,
&status );
/*Create an Entry. */
uuid_create(&entry.id, &status);
entry.name = (dced_string_t)("NEWERprinter");
entry.description = (dced_string_t)
("Configuration for a new printer.");
entry.storage_tag = (dced_string_t)("/etc/NEWprinter");
/* create the attributes */
data.count = 1;
num_strings = 1;
data.list = (sec_attr_t *)
malloc( data.count * sizeof(sec_attr_t) );
data.list->attr_id = dced_g_uuid_fileattr;
data.list->attr_value.attr_encoding =
sec_attr_enc_printstring_array;
str_size = sizeof(sec_attr_enc_str_array_t) + num_strings
* sizeof(sec_attr_enc_printstring_p_t);
attr_array = (sec_attr_enc_str_array_t *)malloc(str_size);
data.list->attr_value.tagged_union.string_array = attr_array;
attr_array->num_strings = num_strings;
attr_array->strings[0] = (dced_string_t)
("New printer configuration data");
dced_hostdata_create( dced_bh, &entry, &data, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_entry_add
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
2 – dced_hostdata_read
NAME
dced_hostdata_read - Reads a hostdata item maintained by dced
on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_read( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
uuid_t *attr_uuid,
sec_attr_t **data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID associated with the data
to read.
attr_uuid
Specifies the UUID associated with an attribute of the data.
The attribute is either plain text (dced_g_uuid_fileattr) or
binary (dced_g_uuid_binfileattr). Some vendors may allow other
attributes.
Output
data
Returns the data for the item. See the sec_intro reference
page for details on the sec_attr_t data type.
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_cant_open_storage_file
dced_s_invalid_attr_type
dced_s_no_memory
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_read() routine returns a hostdata item maintained
by dced on a specific host. The standard data items include the
cell name, a list of cell aliases, the host name, a list of UUID-
program pairs (post_processors), and the DCE configuration database,
among other items. For programming convenience, the following
global variables are defined for the entry_uuid of some standard
data items:
dced_g_uuid_cell_name
dced_g_uuid_cell_aliases
dced_g_uuid_host_name
dced_g_uuid_hostdata_post_proc
dced_g_uuid_dce_cf_db
dced_g_uuid_pe_site
dced_g_uuid_svc_routing
Other host-specific data items may also be maintained by the
hostdata service. The UUIDs for these are established when the
data item is created (See dced_hostdata_create()). After the
applications reads host data and when it is done with the data,
it should call the dced_objects_release() routine to release the
resources allocated.
Each hostdata item for a specific host is stored in a local file.
The name of an item's storage file is indicated in the storage tag
field of each dced hostdata entry.
You can also use the dced_object_read() routine to read the text
of a hostdata item. You might use this routine if your application
needs to read data for other host services (srvrconf, srvrexec, or
keytab) in addition to data for the hostdata service.
Prior to calling the dced_hostdata_read() routine, the
application must have established a valid dced binding handle
to the hostdata service by calling either the dced_binding_create()
or dced_binding_from_rpc_binding() routine.
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_hostdata_write
NAME
dced_hostdata_write - Replaces an existing hostdata item
maintained by dced on a specific host
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_write( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
dced_attr_list_t *data,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the Host Data service
on a specific host.
entry_uuid
Specifies the hostdata entry UUID to associate with the data
to be written.
data
Specifies the data to write. The dced_attr_list_t consists
of a count of the number of attributes, and an array of
attributes of type sec_attr_t. The reference OSF
implementation has one attribute for a hostdata item (file
contents). However some vendors may require multiple
attributes.
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
db_s_bad_index_type
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_open_storage_file
dced_s_no_postprocessors
dced_s_postprocessor_file_fail
dced_s_postprocessor_spawn_fail
dced_s_unknown_attr_type
sec_acl_invalid_permission
uuid_s_bad_version
DESCRIPTION
The dced_hostdata_write() routine replaces existing data for a
hostdata item maintained by dced on a specific host. If the
entry_uuid is not one maintained be dced, an error is returned
and a new entry is not created. Use dced_hostdata_create() to
create a new entry.
Prior to calling the dced_hostdata_write() routine, the
application must have established a valid dced binding
handle to the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
RELATED INFORMATION
Routines: dced_hostdata_read
dced_hostdata_create
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
4 – dced_hostdata_delete
NAME
dced_hostdata_delete - Deletes a hostdata item from a specific
host and removes the associated entry
from dced
SYNOPSIS
#include <dce/dced.h>
void dced_hostdata_delete( dced_binding_handle_t dced_bh,
uuid_t *entry_uuid,
error_status_t *status );
PARAMETERS
Input
dced_bh
Specifies the dced binding handle for the hostdata service
on a specific host.
entry_uuid
Specifies the UUID of the hostdata entry (and associated data)
to delete.
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
db_s_bad_index_type
db_s_del_failed
db_s_iter_not_allowed
db_s_key_not_found
dced_s_bad_binding
dced_s_cant_remove_storage_file
dced_s_not_found
sec_acl_invalid_permission
DESCRIPTION
The dced_hostdata_delete() routine deletes a hostdata item (a file)
from a specific host, and removes the associated entry from the host
data service of that host's dced.
If you want to only make the data inaccessible remotely but not
delete it, use the dced_entry_remove() routine which only removes
the data's hostdata entry.
Prior to calling the dced_hostdata_delete() routine, the
application must have established a valid dced binding handle
for the hostdata service by calling either the
dced_binding_create() or dced_binding_from_rpc_binding()
routine.
WARNINGS
Do not delete the standard hostdata items such as cell_name,
cell_aliases, host_name, post_processors, or dce_cf.db. This
will cause operational problems for the host.
RELATED INFORMATION
Routines: dced_entry_remove
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.