---

The PDS Agent API

Compounds
struct	_pds_entity_id_t_struct
struct	_pds_context_id_t_struct
struct	_pds_domain_id_t_struct
struct	_pds_entity_data_t_struct
struct	_pds_entity_change_event_struct
struct	_pds_context_change_event_struct
struct	_pds_domain_change_event_struct
Defines
#define	PDS_IP_PORT   ATL_CHAR_CONS('C','I','P','P')
#define	PDS_IP_HOST   ATL_CHAR_CONS('C','I','P','H')
#define	PDS_IP_ADDR   ATL_CHAR_CONS('C','I','P','A')
#define	PDS_ID_SIZE   32
#define	PDS_ENTITY_CHANGE_BASE_VAL   300
#define	PDS_ENTITY_CHANGE_CREATION   (PDS_ENTITY_CHANGE_BASE_VAL + 1)
#define	PDS_ENTITY_CHANGE_ATTRS   (PDS_ENTITY_CHANGE_BASE_VAL + 2)
#define	PDS_ENTITY_CHANGE_BIND   (PDS_ENTITY_CHANGE_BASE_VAL + 3)
#define	PDS_ENTITY_CHANGE_UNBIND   (PDS_ENTITY_CHANGE_BASE_VAL + 4)
#define	PDS_ENTITY_CHANGE_DELETION   (PDS_ENTITY_CHANGE_BASE_VAL + 5)
#define	PDS_ENTITY_CHANGE_DATA   (PDS_ENTITY_CHANGE_BASE_VAL + 6)
#define	PDS_CONTEXT_CHANGE_BASE_VAL   320
#define	PDS_CONTEXT_CHANGE_CREATION   (PDS_CONTEXT_CHANGE_BASE_VAL + 1)
#define	PDS_CONTEXT_CHANGE_ATTRS   (PDS_CONTEXT_CHANGE_BASE_VAL + 2)
#define	PDS_CONTEXT_CHANGE_BIND   (PDS_CONTEXT_CHANGE_BASE_VAL + 3)
#define	PDS_CONTEXT_CHANGE_UNBIND   (PDS_CONTEXT_CHANGE_BASE_VAL + 4)
#define	PDS_CONTEXT_CHANGE_DELETION   (PDS_CONTEXT_CHANGE_BASE_VAL + 5)
#define	PDS_DOMAIN_CHANGE_BASE_VAL   350
#define	PDS_DOMAIN_CHANGE_CONTEXT_CHANGE   (PDS_DOMAIN_CHANGE_BASE_VAL + 1)
#define	PDS_DOMAIN_CHANGE_ENTITY_CHANGE   (PDS_DOMAIN_CHANGE_BASE_VAL + 2)
#define	OnlyEntityBindings   0x1
#define	OnlyContextBindings   0x2
#define	GetDataBuffer   0x2
#define	GetDataSize   0x4
#define	GetDataType   0x8
Typedefs
typedef _pds_service_struct *	pds_service
typedef _pds_entity_id_t_struct	pds_entity_id_t
typedef _pds_entity_id_t_struct *	pds_entity_id_t_ptr
typedef _pds_context_id_t_struct	pds_context_id_t
typedef _pds_context_id_t_struct *	pds_context_id_t_ptr
typedef _pds_domain_id_t_struct	pds_domain_id_t
typedef _pds_domain_id_t_struct *	pds_domain_id_t_ptr
typedef _pds_entity_data_t_struct	pds_entity_data_t
typedef _pds_entity_data_t_struct *	pds_entity_data_t_ptr
typedef _pds_entity_change_event_struct	pds_entity_change_event
typedef _pds_entity_change_event_struct *	pds_entity_change_event_ptr
typedef _pds_context_change_event_struct	pds_context_change_event
typedef _pds_context_change_event_struct *	pds_context_change_event_ptr
typedef _pds_domain_change_event_struct	pds_domain_change_event
typedef _pds_domain_change_event_struct *	pds_domain_change_event_ptr
Functions
pds_service	pds_service_open (attr_list contact_attrs)
int	pds_service_close (pds_service service_to_close)
int	pds_shutdown_server (pds_service)
int	pds_lookup_string (pds_domain_id_t domain_id, const char *fullname, char **value)
int	pds_bind_string (pds_domain_id_t domain_id, const char *fullname, const char *value)
int	pds_lookup_int (pds_domain_id_t domain_id, const char *fullname, int *value)
int	pds_bind_int (pds_domain_id_t domain_id, const char *fullname, int value)
int	pds_lookup_blob (pds_domain_id_t domain_id, const char *fullname, char **value)
int	pds_bind_blob (pds_domain_id_t domain_id, const char *fullname, char *value, unsigned int length)
int	pds_bulk_load_from_URL (pds_service s, const char *url)
pds_domain_id_t	pds_create_domain (pds_service s, const char *domain_name, const char *domain_type, int domain_version, const char *application_name)
pds_domain_id_t	pds_open_domain (pds_service s, const char *domain_name, const char *domain_type, int domain_version, const char *application_name)
int	pds_remove_domain (pds_domain_id_t id)
int	pds_find_matching_domains (pds_service s, const char *domain_name, const char *domain_type, int domain_version, const char *application_name, pds_domain_id_t **matches)
int	pds_set_domain_attrs (pds_domain_id_t d_id, attr_list al)
int	pds_get_domain_attrs (pds_domain_id_t d_id, attr_list al)
pds_context_id_t	pds_create_context (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id)
int	pds_remove_context (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id)
int	pds_remove_context_by_id (pds_domain_id_t d_id, pds_context_id_t c_id)
pds_context_id_t	pds_get_root_context (pds_domain_id_t d_id)
char **	pds_get_binding_list (pds_domain_id_t d_id, const char *name, int opt_mask)
char **	pds_get_binding_list_id (pds_domain_id_t d_id, pds_context_id_t c_id, int opt_mask)
pds_entity_id_t	pds_create_entity (pds_domain_id_t d_id, const char *fullname, pds_context_id_t c_id, pds_entity_data_t *edata, attr_list attribute_list)
int	pds_remove_entity (pds_domain_id_t d_id, const char *fullname, pds_context_id_t c_id)
int	pds_remove_entity_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id)
int	pds_bind_entity_to_name (pds_domain_id_t d_id, const char *source_name, pds_context_id_t source_context, const char *new_name, pds_context_id_t new_name_context)
int	pds_bind_entity_to_name_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id, const char *new_name, pds_context_id_t new_name_context)
int	pds_unbind_entity_from_name (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id)
pds_entity_id_t	pds_resolve_entity_name (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id)
ECSinkHandle	pds_register_for_domain_changes (CManager cm, pds_domain_id_t d_id, ECTypedHandlerFunction func_ptr, void *client_data)
ECSinkHandle	pds_register_for_entity_changes (CManager cm, pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, ECTypedHandlerFunction func_ptr, void *client_data)
ECSinkHandle	pds_register_for_context_changes (CManager cm, pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, ECTypedHandlerFunction func_ptr, void *client_data)
int	pds_cancel_changes_registration (ECSinkHandle sink_handle)
int	pds_get_entity_data (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, pds_entity_data_t *edata, int opt_mask)
int	pds_get_entity_data_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id, pds_entity_data_t *edata, int opt_mask)
int	pds_set_entity_data (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, pds_entity_data_t *edata, int opt_mask)
int	pds_set_entity_data_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id, pds_entity_data_t *edata, int opt_mask)
int	pds_get_entity_attributes (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, attr_list attrs)
int	pds_get_entity_attributes_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id, attr_list attributes)
int	pds_set_entity_attributes (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, attr_list attrs, int opt)
int	pds_set_entity_attributes_by_id (pds_domain_id_t d_id, pds_entity_id_t e_id, attr_list attributes, int opt)
pds_entity_id_t *	pds_find_matching_entities (pds_domain_id_t d_id, const char *name, pds_context_id_t c_id, attr_list attributes)
pds_entity_id_t *	pds_find_matching_entities_by_name (pds_domain_id_t d_id, const char *fullname, attr_list attributes)
CManager	pds_get_CManager ()
Variables
pds_entity_id_t	null_pds_entity_id
pds_context_id_t	null_pds_context_id
pds_domain_id_t	null_pds_domain_id

---

Define Documentation

#define PDS_ENTITY_CHANGE_CREATION   (PDS_ENTITY_CHANGE_BASE_VAL + 1)

UID for the ENTITY_CHANGE_CREATION event. Submitted to the entity's update channel when the entity is created. Note that the semantics of update subscription in PDS allow interest to be registered for entities that don't exist at subscription time.

#define PDS_ENTITY_CHANGE_ATTRS   (PDS_ENTITY_CHANGE_BASE_VAL + 2)

UID for the ENTITY_CHANGE_ATTRS event. Submitted to the entity's update channel when the attributes of the entity are updated.

#define PDS_ENTITY_CHANGE_BIND   (PDS_ENTITY_CHANGE_BASE_VAL + 3)

UIDs for the ENTITY_CHANGE_BIND/UNBIND events. Submitted to the entity's update channel when the entity is (un)bound (from)to a particular name in a PDS domain.

#define PDS_ENTITY_CHANGE_DELETION   (PDS_ENTITY_CHANGE_BASE_VAL + 5)

UID for the ENTITY_CHANGE_DELETION event. Submitted to the entity's update channel when the entity is deleted from its hosting PDS service instance.

#define PDS_ENTITY_CHANGE_DATA   (PDS_ENTITY_CHANGE_BASE_VAL + 6)

UID for the ENTITY_CHANGE_DATA event. Submitted to the entity's update channel when the entity's data is modified.

---

Typedef Documentation

typedef struct _pds_service_struct* pds_service

Opaque structure identifying a remote PDS service instance.

typedef struct _pds_entity_id_t_struct pds_entity_id_t

ID for PDS entities

typedef struct _pds_entity_id_t_struct * pds_entity_id_t_ptr

ID for PDS entities

typedef struct _pds_context_id_t_struct pds_context_id_t

ID for PDS contexts

typedef struct _pds_context_id_t_struct * pds_context_id_t_ptr

ID for PDS contexts

typedef struct _pds_domain_id_t_struct pds_domain_id_t

ID for PDS domains

typedef struct _pds_domain_id_t_struct * pds_domain_id_t_ptr

ID for PDS domains

typedef struct _pds_entity_data_t_struct pds_entity_data_t

Typedef for entity data stored in PDS. The structure contains a pointer to the data buffer, the size of the data buffer, and an attr_value indicating the type of the data.

typedef struct _pds_entity_data_t_struct * pds_entity_data_t_ptr

Typedef for entity data stored in PDS. The structure contains a pointer to the data buffer, the size of the data buffer, and an attr_value indicating the type of the data.

---

Function Documentation

pds_service pds_service_open (  attr_list    contact_attrs )

Open a connection to a PDS service instance. The service may be local or remote as specified by the attribute list given as a parameter. Parameters: contact_attrs  The attribute list used by PDS to contact the PDS service instance through CM. Returns: A pointer to a pds_service structure identifying the remote service instance. Returns NULL if the connection cannot be opened.

int pds_service_close (  pds_service    service_to_close )

Close the connection to the given PDS service instance. Parameters: service_to_close  The local "handle" to the service instance to be closed. If NULL, this function has no effect. Returns: Returns 1 if successful, -1 otherwise. Examples: basic.c, and basic2.c.

int pds_shutdown_server (  pds_service    )

Request that the PDS service instance identified by the parameter shut down. Currently, the service instance is not required to honor the request. Parameters: pds_service  The local "handle" to the service instance to be shut down. If NULL, this function has no effect. Returns: Returns 1 if the request is successfully made, -1 otherwise. Note that this return value does not indicate whether or not the service instance responded to the request.

int pds_lookup_string (  pds_domain_id_t    domain_id, const char *    fullname, char **    value )

Look up a string value. Parameters: domain_id  Identifies the domain of the requested value. fullname  This is the context name ("key") for the requested string value. value  A pointer-to-pointer-to-char in which to store the resulting value. This function allocates memory for this string which must be freed by the caller using free(). If the value is not present or is not an Attr_String value, this parameter is set to NULL. Returns: Returns 1 if successful (an Attr_String value was found using the specified name and successfully returned) and -1 otherwise.

int pds_bind_string (  pds_domain_id_t    domain_id, const char *    fullname, const char *    value )

Bind a string to a name in the given domain. Binding creates an association between the context name and the value which can be queried at a later time. Parameters: domain_id  Identifies the domain in which to create the binding. fullname  Context name to use in the binding. value  String to bind. If value is NULL, a binding to a NULL string is created. Returns: Returns 1 if successful, -1 otherwise.

int pds_lookup_int (  pds_domain_id_t    domain_id, const char *    fullname, int *    value )

Look up an integer (Attr_Int4) value. Parameters: domain_id  Identifies the domain of the requested value. fullname  This is the context name ("key") for the requested value. value  A pointer-to-int in which to store the resulting value. If the value is not present or is not an Attr_Int4 value, this parameter is set to NULL. Returns: Returns 1 if successful (an Attr_Int4 value was found using the specified name and successfully returned) and -1 otherwise.

int pds_bind_int (  pds_domain_id_t    domain_id, const char *    fullname, int    value )

Bind an integer to a name in the given domain. Binding creates an association between the context name and the value which can be queried at a later time. Parameters: domain_id  Identifies the domain in which to create the binding. fullname  Context name to use in the binding. value  Integer value to bind. Returns: Returns 1 if successful, -1 otherwise.

int pds_lookup_blob (  pds_domain_id_t    domain_id, const char *    fullname, char **    value )

Look up a blob (binary large object - Attr_Unknown) value. Parameters: domain_id  Identifies the domain of the requested value. fullname  This is the context name ("key") for the requested value. value  A pointer-to-pointer-to-char in which to store the resulting value. This function allocates memory for this string which must be freed by the caller using free(). If the value is not present or is not an Attr_Unknown value, this parameter is set to NULL. Returns: Returns 1 if successful (an Attr_Unknown value was found using the specified name and successfully returned) and -1 otherwise.

int pds_bind_blob (  pds_domain_id_t    domain_id, const char *    fullname, char *    value, unsigned int    length )

Bind a blob (binary large object) to a name in the given domain. Binding creates an association between the context name and the value which can be queried at a later time. Parameters: domain_id  Identifies the domain in which to create the binding. fullname  Context name to use in the binding. value  Byte buffer containing object to bind. length  Length of the byte buffer. Returns: Returns 1 if successful, -1 otherwise.

int pds_bulk_load_from_URL (  pds_service    s, const char *    url )

Load the directory with a content file found at the given URL. Testing or initialization purposes may require that a service instance contain a known set of information. This function retrieves an XML file containing one or more PDS bulk-load sets and adds its contents to the in-memory state of the instance. The format of the XML file is defined elsewhere (yeah right). The end state of the service instance is the union of any content existing when this function is called and the content of the file. Common context values between pre-existing content and the file are bound to entity values found in the file. Existing event registrations are not affected, and all defined change events are fired. The bulk-load may cause entity placeholders to be promoted to live entities; i.e. there is no way currently to register interest in an entity using the bulk-load process without explicitly creating it (implying that no creation events are fired by the bulk-load). Currently the service instance is not required to honor the request to perform the bulk-load. Parameters: s  Handle for the service instance. url  Universal Resource Locator specifying the location of the XML file containing the desired bulk-load set(s). Returns: Returns 1 if the request is completed successfully.

pds_domain_id_t pds_create_domain (  pds_service    s, const char *    domain_name, const char *    domain_type, int    domain_version, const char *    application_name )

Create a new domain in the given service instance. If a domain matching the given information already exists, its domain ID is returned instead. Deprecated: This function will go away. Use pds_open_domain instead. Parameters: s  The handle to the service instance. domain_name  Name of the new domain. domain_type  Type of the new domain. domain_version  Version number. application_name  Self-explanatory. Returns: Returns the new domain ID. If the operation is unsuccessful, a null domain ID (equivalent to null_pds_domain_id) is returned instead.

pds_domain_id_t pds_open_domain (  pds_service    s, const char *    domain_name, const char *    domain_type, int    domain_version, const char *    application_name )

Open an existing domain in the given service instance. If no domain matching the given parameters is found, a new domain is created and its ID returned. Deprecated: This function will go away. Use pds_open_domain instead. Parameters: s  The handle to the service instance. domain_name  Name of the new domain. domain_type  Type of the new domain. domain_version  Version number. application_name  Self-explanatory. Returns: Returns the opened domain ID. If the operation is unsuccessful, a null domain ID (equivalent to null_pds_domain_id) is returned instead.

int pds_remove_domain (  pds_domain_id_t    id )

Remove the indicated domain from its service instance. The handle to the instance is not necessary since domains know what service instance they belong to. All events for context destruction and entity unbinding/destruction are fired. Parameters: id  The domain to remove. Returns: Returns 1 if the operation is successful, 0 otherwise.

int pds_find_matching_domains (  pds_service    s, const char *    domain_name, const char *    domain_type, int    domain_version, const char *    application_name, pds_domain_id_t **    matches )

Locate domains matching the given characteristics. Limited string-matching is performed; i.e. wildcards are not generally supported. If you do not want to search based on one of the items, do not specify a value for that item (pass NULL for domain_type, for example). All domains matching the given criteria are returned in the NULL-terminated list matches. The caller is responsible for calling free() on this list when finished using it. Parameters: s  The PDS service instance to search in. domain_name  Name criteria. domain_type  Type criteria. domain_version  Version number. application_name  Self-explanatory. matches  NULL-terminated list of pds_domain_id_t containing the matches found by the search. Pass the address of a pds_domain_id_t*. Will be set to NULL if there are no matches. Returns: Returns 1 if the operation is successful, -1 if there was a problem. Note that a search returning no domain IDs is still considered a successful operation - check the matches parameter for results of the search.

int pds_set_domain_attrs (  pds_domain_id_t    d_id, attr_list    al )

Set/get the attributes of a domain. The given attribute list replaces the previous attribute list. Parameters: d_id  The domain ID desired. al  The new attribute list to associate with the domain. Returns: Returns 1 if the operation was successful, -1 otherwise.

pds_context_id_t pds_create_context (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id )

Create a context in the given domain. The name and c_id parameters are used as follows. String-based naming for contexts and entities in PDS is the preferred method, and results in names like "/path/to/the/entity" being used to identify these objects. In such a name string, "/", "/path", "/path/to", and "/path/to/the" all identify contexts. Each of these contexts has associated with it a context ID. Relative naming applies a "base" context ID to a string-based name. For example, if my_context_ID is the pds_context_id_t corresponding to the context named by "/path/to", then absolute naming using "/path/to/the/entity" and relative naming that applies the string "/the/entity" to my_context_ID both refer to the same object. PDS context functions make use of this property by allowing the caller to specify a context ID. If it is present, relative naming is assumed and the name parameter is used as a string relative to the given context ID. If the context ID is null_pds_context_id, then absolute naming is assumed. Parameters: d_id  The domain in which to create the new context. name  The "trailing component" of the full context name. Must not be NULL; i.e. must contain at least one name component. c_id  The context ID used as a "base context" for the trailing component. Pass null_pds_context_id to indicate that the name parameter contains the entire name for the new context. Returns: Returns a pds_context_id_t identifying the newly created context.

int pds_remove_context (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id )

Remove a context from the given domain. All bindings held by the context are unbound and associated context/entity unbinding events fired. See pds_create_context for a discussion of context naming and the use of name and c_id. Parameters: d_id  The domain from which to remove the indicated context. name  The "trailing component" of the full context name. Must not be NULL; i.e. must contain at least one name component. c_id  The context ID used as a "base context" for the trailing component. Pass null_pds_context_id to indicate that the name parameter contains the entire name for the context. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_remove_context_by_id (  pds_domain_id_t    d_id, pds_context_id_t    c_id )

Remove a context from the given domain, specifying it directly by its ID. All bindings held by the context are unbound and associated context/entity unbinding events fired. Parameters: d_id  The domain from which to remove the indicated context. c_id  The context to remove. Returns: Returns 1 if the operation is successful, -1 otherwise.

pds_context_id_t pds_get_root_context (  pds_domain_id_t    d_id )

Get the context ID of the root context of the domain's namespace. Parameters: d_id  The domain ID of the domain in question. Returns: Returns the pds_context_id_t of the domain's root context.

char** pds_get_binding_list (  pds_domain_id_t    d_id, const char *    name, int    opt_mask )

Get the binding list of a context. The binding list consists of all names bound to either contexts or entities in that context. This function allocates memory for its return value which the caller must release after use by calling free(). Parameters: d_id  The domain ID of the context. name  The absolute name of the context in question. opt_mask  Options mask indicating variations. Pass OnlyEntityBindings to return only names bound to entities in the given context. Pass OnlyContextBindings to return only names bound to contexts. Pass 0 to return all bindings. Returns: Returns a NULL-terminated array of strings as the binding list.

char** pds_get_binding_list_id (  pds_domain_id_t    d_id, pds_context_id_t    c_id, int    opt_mask )

Get the binding list of a context. The binding list consists of all names bound to either contexts or entities in that context. This function allocates memory for its return value which the caller must release after use by calling free(). Parameters: d_id  The domain ID of the context. c_id  The context ID of the context in question. opt_mask  Options mask indicating variations. Pass OnlyEntityBindings to return only names bound to entities in the given context. Pass OnlyContextBindings to return only names bound to contexts. Pass 0 to return all bindings. Returns: Returns a NULL-terminated array of strings as the binding list.

pds_entity_id_t pds_create_entity (  pds_domain_id_t    d_id, const char *    fullname, pds_context_id_t    c_id, pds_entity_data_t *    edata, attr_list    attribute_list )

Create an entity in the given context in the given domain. Relative/absolute naming applies with the fullname and c_id parameters as described in the context API. Parameters: d_id  The domain ID in which to create the entity. fullname  The "trailing component" of the full context name. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base the fullname argument. edata  A pointer to a pds_entity_data_t structure. Pass NULL if no entity data is to be stored. attribute_list  An attr_list to be associated with the entity. Pass NULL if no attributes are to be stored. Returns: Returns the ID of the newly created entity, or null_pds_entity_id if the operation is unsuccessful.

int pds_remove_entity (  pds_domain_id_t    d_id, const char *    fullname, pds_context_id_t    c_id )

Remove an entity from the given domain. Relative/absolute naming applies with the fullname and c_id parameters as described in the context API. Parameters: d_id  The domain ID from which to delete the entity. fullname  The "trailing component" of the full context name. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base the fullname argument. Returns: Returns 1 if the deletion is successful, -1 otherwise.

int pds_remove_entity_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id )

Remove an entity from the given Domain, identifying the entity by its ID. Parameters: d_id  The domain from which to delete the entity. e_id  The ID of the entity to delete. Returns: Returns 1 if the deletion is successful, -1 otherwise.

int pds_bind_entity_to_name (  pds_domain_id_t    d_id, const char *    source_name, pds_context_id_t    source_context, const char *    new_name, pds_context_id_t    new_name_context )

Bind an entity to a name in a specific context. This function expects that the entity is already bound to a name in the domain and so can be identified by that name (relative to a context ID if desired). Thus this function serves to create alternate bindings to a single entity. Parameters: d_id  The domain where the entity should be bound. source_name  The "trailing component" of the name at which the entity can be found. Must not be NULL; i.e. must contain at least one name component. source_context  The context on which to base the source_name. new_name  The "trailing component" of the name to bind the entity. Must not be NULL; i.e. must contain at least one name component. new_name_context  The context on which to base the new_name. Returns: Returns 1 if the new binding is successful, -1 otherwise.

int pds_bind_entity_to_name_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id, const char *    new_name, pds_context_id_t    new_name_context )

Bind an entity to a name in a specific context. This function expects that the entity is identified by its ID. Parameters: d_id  The domain where the entity should be bound. e_id  The ID of the entity to bind. new_name  The "trailing component" of the name to bind the entity. Must not be NULL; i.e. must contain at least one name component. new_name_context  The context on which to base the new_name. Pass pds_null_context_id if name is an absolute name. Returns: Returns 1 if the new binding is successful, -1 otherwise.

int pds_unbind_entity_from_name (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id )

Unbind an entity from a name. name and c_id are used to identify an entity, and then that binding to the entity is removed. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. Returns: Returns 1 if the operation is successful, -1 otherwise.

pds_entity_id_t pds_resolve_entity_name (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id )

Obtain an entity ID from a name. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. Returns: Returns 1 if the operation is successful, -1 otherwise.

ECSinkHandle pds_register_for_domain_changes (  CManager    cm, pds_domain_id_t    d_id, ECTypedHandlerFunction    func_ptr, void *    client_data )

Register for any changes on the given domain. The handler function specified by func_ptr is called with domain update events. Parameters: cm  A CManager value. This can be obtained using the CManager_create() function from CM. d_id  The ID of the domain about which to register for changes. func_ptr  A pointer to a handler function for change events. client_data  A pointer to a data structure that will be passed to the event handler each time an update occurs. For more information, see the ECho documentation. Returns: Returns an ECSinkHandle from ECho. If unsuccessful, returns NULL.

ECSinkHandle pds_register_for_entity_changes (  CManager    cm, pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, ECTypedHandlerFunction    func_ptr, void *    client_data )

Register for any changes on the given entity. The handler function specified by func_ptr is called with entity update events. Parameters: cm  A CManager value. This can be obtained using the CManager_create() function from CM. d_id  The ID of the domain where the entity resides. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. func_ptr  A pointer to a handler function for change events. client_data  A pointer to a data structure that will be passed to the event handler each time an update occurs. For more information, see the ECho documentation. Returns: Returns an ECSinkHandle from ECho. If unsuccessful, returns NULL.

ECSinkHandle pds_register_for_context_changes (  CManager    cm, pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, ECTypedHandlerFunction    func_ptr, void *    client_data )

Register for any changes on the given context. The handler function specified by func_ptr is called with entity update events. Parameters: cm  A CManager value. This can be obtained using the pds_get_CManager() function. d_id  The ID of the domain where the context resides. name  The "trailing component" of the name identifying the context. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. func_ptr  A pointer to a handler function for change events. client_data  A pointer to a data structure that will be passed to the event handler each time an update occurs. For more information, see the ECho documentation. Returns: Returns an ECSinkHandle from ECho. If unsuccessful, returns NULL.

int pds_cancel_changes_registration (  ECSinkHandle    sink_handle )

Cancel the registration for a particular sink handle. Parameters: sink_handle  The sink handle (obtained from one of the registration functions) identifying the event registration to cancel. Returns: Returns 1 if the cancellation is successful, -1 otherwise.

int pds_get_entity_data (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, pds_entity_data_t *    edata, int    opt_mask )

Return the entity data for a particular entity. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. edata  The address of a structure to populate with the entity data. Memory for the structure's data member is allocated automatically and must be released using free(). opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_get_entity_data_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id, pds_entity_data_t *    edata, int    opt_mask )

Return the entity data for a particular entity. The entity is identified by its entity ID. Parameters: d_id  The domain where the entity-name binding exists. e_id  The ID of the entity to be modified. edata  The address of a structure to populate with the entity data. Memory for the structure's data member is allocated automatically and must be released using free(). opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_set_entity_data (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, pds_entity_data_t *    edata, int    opt_mask )

Set the entity data for a particular entity. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. edata  The address of a structure containing the entity data to store. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_set_entity_data_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id, pds_entity_data_t *    edata, int    opt_mask )

Set the entity data for a particular entity. The entity is identified by its entity ID. Parameters: d_id  The domain where the entity-name binding exists. e_id  The ID of the entity to be modified. edata  The address of a structure containing the entity data to store. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_get_entity_attributes (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, attr_list    attrs )

Get the entity attributes for a particular entity. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. attributes  An attr_list to be populated with the entity attributes. Attributes retrieved from the service are merged with existing attributes. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_get_entity_attributes_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id, attr_list    attributes )

Get the entity attributes for a particular entity. The entity is identified by its entity ID. Parameters: d_id  The domain where the entity-name binding exists. e_id  The ID of the entity to be modified. attributes  An attr_list to be populated with the entity attributes. Attributes retrieved from the service are merged with existing attributes. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_set_entity_attributes (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, attr_list    attrs, int    opt )

Set the entity attributes for a particular entity. Parameters: d_id  The domain where the entity-name binding exists. name  The "trailing component" of the name identifying the entity. Must not be NULL; i.e. must contain at least one name component. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. attributes  The attr_list to be stored as the entity attributes. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

int pds_set_entity_attributes_by_id (  pds_domain_id_t    d_id, pds_entity_id_t    e_id, attr_list    attributes, int    opt )

Set the entity attributes for a particular entity. The entity is identified by its entity ID. Parameters: d_id  The domain where the entity-name binding exists. e_id  The ID of the entity to be modified. attributes  The attr_list to be stored as the entity attributes. opt_mask  TBA. Returns: Returns 1 if the operation is successful, -1 otherwise.

pds_entity_id_t* pds_find_matching_entities (  pds_domain_id_t    d_id, const char *    name, pds_context_id_t    c_id, attr_list    attributes )

Search the domain for entities matching the attributes contained in attributes. This function can be used to search for entities across the entire domain or only those bound in a given context. This context is identified in this function by the absolute/relative naming scheme described in the Context API. If name is NULL and c_id is null_pds_context_id, then the entire domain is searched. Subset-equality is used for the match - if the given attribute list is exactly equal or a subset of the attribute list of an entity, the entity is considered a match. Parameters: d_id  The domain in which to perform the search. name  The "trailing component" of the name identifying the context to be searched. Must not be NULL if c_id is not pds_null_context_id. c_id  The context on which to base name. Pass pds_null_context_id if name is an absolute name. attributes  An attr_list to match against attributes contained in potential matching entities. Returns: Returns a pds_null_entity_id -terminated list of entity IDs that match the search. This list is allocated by the function and must be released by the caller using free(). If the search returns no entities, the return value is NULL.

pds_entity_id_t* pds_find_matching_entities_by_name (  pds_domain_id_t    d_id, const char *    fullname, attr_list    attributes )

Search the domain for entities matching the attributes contained in attributes. This function can be used to search for entities across the entire domain or only those bound in a given context. This context is identified in this function by the absolute name fullname. If fullname is NULL, then the entire domain is searched. Subset-equality is used for the match - if the given attribute list is exactly equal or a subset of the attribute list of an entity, the entity is considered a match. Parameters: d_id  The domain in which to perform the search. fullname  The name of a context to limit the search. If this parameter is NULL, the entire domain is searched. attributes  An attr_list to match against attributes contained in potential matching entities. Returns: Returns a pds_null_entity_id -terminated list of entity IDs that match the search. This list is allocated by the function and must be released by the caller using free(). If the search returns no entities, the return value is NULL.

CManager pds_get_CManager (    )

Returns the CManager value used by the PDS client-side library. Returns: Returns a CManager.

---

Variable Documentation

pds_entity_id_t null_pds_entity_id

A pre-defined NULL entity ID. Conceptually equivalent to a NULL char*.

pds_context_id_t null_pds_context_id

A pre-defined NULL context ID. Conceptually equivalent to a NULL char*.

pds_domain_id_t null_pds_domain_id

A pre-defined NULL domain ID. Conceptually equivalent to a NULL char*.

---