LassoDataService

LassoDataService — ID-WSF Data Service profile

Synopsis

                    LassoDataService;
LassoDataService*   lasso_data_service_new              (LassoServer *server);
LassoDataService*   lasso_data_service_new_full         (LassoServer *server,
                                                         LassoDiscoResourceOffering *offering);
lasso_error_t       lasso_data_service_init_query       (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id,
                                                         const char *security_mech_id);
lasso_error_t       lasso_data_service_add_query_item   (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id);
lasso_error_t       lasso_data_service_build_modify_response_msg
                                                        (LassoDataService *service);
lasso_error_t       lasso_data_service_build_response_msg
                                                        (LassoDataService *service);
lasso_error_t       lasso_data_service_process_query_response_msg
                                                        (LassoDataService *service,
                                                         const char *message);
lasso_error_t       lasso_data_service_get_answer       (LassoDataService *service,
                                                         xmlNode **output);
lasso_error_t       lasso_data_service_get_answers      (LassoDataService *service,
                                                         GList **output);
lasso_error_t       lasso_data_service_get_answers_by_select
                                                        (LassoDataService *service,
                                                         const char *select,
                                                         GList **output);
lasso_error_t       lasso_data_service_get_answers_by_item_id
                                                        (LassoDataService *service,
                                                         const char *item_id,
                                                         GList **output);
lasso_error_t       lasso_data_service_init_modify      (LassoDataService *service,
                                                         const char *security_mech_id);
lasso_error_t       lasso_data_service_add_modification (LassoDataService *service,
                                                         const gchar *select,
                                                         xmlNode *xmlData,
                                                         gboolean overrideAllowed,
                                                         time_t *notChangedSince,
                                                         LassoDstModification **output);
lasso_error_t       lasso_data_service_process_modify_response_msg
                                                        (LassoDataService *service,
                                                         const gchar *soap_msg);
lasso_error_t       lasso_data_service_process_request_msg
                                                        (LassoDataService *service,
                                                         const char *message,
                                                         const char *security_mech_id);
lasso_error_t       lasso_data_service_validate_request (LassoDataService *service);
lasso_error_t       lasso_data_service_build_query_response_msg
                                                        (LassoDataService *service);
lasso_error_t       lasso_data_service_get_query_item   (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id,
                                                         LassoDstQueryItem **output);
void                lasso_data_service_set_resource_data
                                                        (LassoDataService *service,
                                                         const xmlNode *resource_data);
xmlNode *           lasso_data_service_get_resource_data
                                                        (LassoDataService *service);

Description

DataService allows Attribute Consumers (WSC) to request an Attribute Provider (WSP) to get or modify data about users with their consent.

Following up on LassoDiscovery first example, it created a service object, this is a LassoDataService instance. This example continues from that step and retrieves the name of the principal:

char *soap_answer;            // SOAP answer from data service
xmlNode *principal_name;      // libxml2 xmlNode with the principal name

service = lasso_discovery_get_service(discovery);
lasso_data_service_init_query(service, "/pp:PP/pp:InformalName", NULL);
lasso_data_service_build_request_msg(service);

// service must perform SOAP call to LASSO_WSF_PROFILE(service)->msg_url
// the SOAP message is LASSO_WSF_PROFILE(service)->msg_body.  The answer
// is stored in char* soap_answer;

lasso_data_service_process_query_response_msg(service, soap_answer);
principal_name = lasso_data_service_get_answer(service, "/pp:PP/pp:InformalName");

// app should probably then use xmlNodeGetContent libxml2 function to get
// access to node content.

Details

LassoDataService

typedef struct {
	LassoWsfProfile parent;
} LassoDataService;

lasso_data_service_new ()

LassoDataService*   lasso_data_service_new              (LassoServer *server);

Creates a new LassoDataService.

server :

the LassoServer

Returns :

a newly created LassoDataService object; or NULL if an error occured.

lasso_data_service_new_full ()

LassoDataService*   lasso_data_service_new_full         (LassoServer *server,
                                                         LassoDiscoResourceOffering *offering);

Creates a new LassoDataService.

server :

the LassoServer

offering :

the LassoDiscoResourceOffering

Returns :

a newly created LassoDataService object; or NULL if an error occured.

lasso_data_service_init_query ()

lasso_error_t       lasso_data_service_init_query       (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id,
                                                         const char *security_mech_id);

Initializes a new dst:Query request, asking for element select (with optional itemID set to item_id). item_id may be NULL only if the query won't contain other query items. You must follow this constraint, it will not be checked.

If both select and item_id are NULL, only a skeleton request is created and calls to lasso_data_service_add_query_item() will need to be done.

service :

a LassoDataService

select :

resource selection string (typically a XPath query)

item_id :

query item identifier (optional). allow-none.

security_mech_id :

a security mechanism id. allow-none.

Returns :

0 on success; or a negative value otherwise.

lasso_data_service_add_query_item ()

lasso_error_t       lasso_data_service_add_query_item   (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id);

Adds a dst:QueryItem to the current dst:Query request. If there are already query item in the request and itemId is NULL, the call will fail.

service :

a LassoDataService

select :

resource selection string (typically a XPath query)

item_id :

query item identifier

Returns :

0 if sucessfull, an error code otherwise.

lasso_data_service_build_modify_response_msg ()

lasso_error_t       lasso_data_service_build_modify_response_msg
                                                        (LassoDataService *service);

lasso_data_service_build_response_msg ()

lasso_error_t       lasso_data_service_build_response_msg
                                                        (LassoDataService *service);

Builds a dst:QueryResponse message.

service :

a LassoDataService

Returns :

0 on success; or a negative value otherwise.

lasso_data_service_process_query_response_msg ()

lasso_error_t       lasso_data_service_process_query_response_msg
                                                        (LassoDataService *service,
                                                         const char *message);

Processes a dst:Query message. Rebuilds a request object from the message and extracts ResourcedID.

service :

a LassoDataService

message :

the dst query response message

Returns :

0 on success; or a negative value otherwise.

lasso_data_service_get_answer ()

lasso_error_t       lasso_data_service_get_answer       (LassoDataService *service,
                                                         xmlNode **output);

Get the first xmlNode of the first Data element of the QueryResponse message.

service :

a LassoDataService object.

output :

an xmlNode** pointer where to put the xmlNode* of the result. out.

Returns :

0 if sucessful, an error code otherwise.

lasso_data_service_get_answers ()

lasso_error_t       lasso_data_service_get_answers      (LassoDataService *service,
                                                         GList **output);

Get all the xmlNode content of the first Data element of the QueryResponse message.

service :

a LassoDataService object.

output :

an xmlNode** pointer where to put the xmlNode* of the result. transfer full. allow-none full. element-type xmlNode.

Returns :

0 if sucessful, an error code otherwise.

lasso_data_service_get_answers_by_select ()

lasso_error_t       lasso_data_service_get_answers_by_select
                                                        (LassoDataService *service,
                                                         const char *select,
                                                         GList **output);

Returns the answers for the specified select request.

service :

a LassoDataService

select :

resource selection string (typically a XPath query)

output :

a GList** to store a GList* containing the result, it must be freed.. allow-none. element-type xmlNode.

Returns :

0 if successful, an error code otheriwse

lasso_data_service_get_answers_by_item_id ()

lasso_error_t       lasso_data_service_get_answers_by_item_id
                                                        (LassoDataService *service,
                                                         const char *item_id,
                                                         GList **output);

Returns the answers for the specified itemID request.

service :

a LassoDataService

item_id :

query item identifier

output :

a GList** to store a GList* containing the result, it must be freed.. allow-none. element-type xmlNode.

Returns :

0 if successful, an error code otherwise

lasso_data_service_init_modify ()

lasso_error_t       lasso_data_service_init_modify      (LassoDataService *service,
                                                         const char *security_mech_id);

Initialize a Data Service Template Modify request using a command to select some data, and an XML fragment to replace the selected data.

service :

a LassoDataService object

security_mech_id :

a security mechanism id. allow-none.

Returns :

0 if successful, an error code otherwise.

lasso_data_service_add_modification ()

lasso_error_t       lasso_data_service_add_modification (LassoDataService *service,
                                                         const gchar *select,
                                                         xmlNode *xmlData,
                                                         gboolean overrideAllowed,
                                                         time_t *notChangedSince,
                                                         LassoDstModification **output);

Add a new modification to the current modify request. If overrideAllowed is FALSE, xmlData must absolutely be present. Refer to the ID-WSF DST 1.0 specification for the semantic of the created message.

service :

a LassoDataService object

select :

a selector string

xmlData :

optional NewData content. allow-none.

overrideAllowed :

whether to permit delete or replace of existings. allow-none. default FALSE.

notChangedSince :

allow-none. allow-none.

output :

a LassoDstModification** pointer where to put the LassoDstModification of the result. out.

Returns :

0 if successful and the new modification object in *output, an error code otherwise.

lasso_data_service_process_modify_response_msg ()

lasso_error_t       lasso_data_service_process_modify_response_msg
                                                        (LassoDataService *service,
                                                         const gchar *soap_msg);

Process a modify response message.

service :

a LassoDataService

soap_msg :

the SOAP message

Returns :

0 on success; or a negative value otherwise.

lasso_data_service_process_request_msg ()

lasso_error_t       lasso_data_service_process_request_msg
                                                        (LassoDataService *service,
                                                         const char *message,
                                                         const char *security_mech_id);

service :

a LassoDataService object

message :

a C string containing the SOAP request

security_mech_id:(allow-none) :

a C string describing the required security mechanism or NULL

Returns :

0 if successfull, an error code otherwise.

lasso_data_service_validate_request ()

lasso_error_t       lasso_data_service_validate_request (LassoDataService *service);

lasso_data_service_build_query_response_msg ()

lasso_error_t       lasso_data_service_build_query_response_msg
                                                        (LassoDataService *service);

lasso_data_service_get_query_item ()

lasso_error_t       lasso_data_service_get_query_item   (LassoDataService *service,
                                                         const char *select,
                                                         const char *item_id,
                                                         LassoDstQueryItem **output);

Look up the first query item in the current request matching the given criteria, select or item_id. At least one of the criteria must be present for the call to succeed.

service :

a LassoDataService

select :

the select string of the query item to found

item_id :

the item id of the query item to found

output :

transfer none. transfer none.

Returns :

0 if successful, an error code otherwise.

lasso_data_service_set_resource_data ()

void                lasso_data_service_set_resource_data
                                                        (LassoDataService *service,
                                                         const xmlNode *resource_data);

Set the resource data content.

service :

a LassoDataService object

resource_data :

an xmlnode representing the resource data of the service. allow-none.

lasso_data_service_get_resource_data ()

xmlNode *           lasso_data_service_get_resource_data
                                                        (LassoDataService *service);

Return the XML resrouce data in this data service.

service :

a LassoDataService object

Returns :

a newly allocated xmlNode or NULL.. transfer full. allow-none full.