LassoDataService

## LassoDataService LassoDataService — ID-WSF Data Service profile |

## Synopsis

    struct              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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    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

### struct LassoDataService

    struct LassoDataService {
    	LassoWsfProfile parent;
    };

### 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][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` : | if not NULL, give the time (as a local time_t value) of the last known modification to the datas, it is used to permit secure concurrent accesses. [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` : | a LassoDstQueryItem handle to store the result object, its reference count is not incremented. [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]