LassoDataService: Lasso Reference Manual

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

## Functions

LassoDataService * | lasso_data_service_new ()
LassoDataService * | lasso_data_service_new_full ()
lasso_error_t | lasso_data_service_init_query ()
lasso_error_t | lasso_data_service_add_query_item ()
lasso_error_t | lasso_data_service_build_modify_response_msg ()
lasso_error_t | lasso_data_service_build_response_msg ()
lasso_error_t | lasso_data_service_process_query_response_msg ()
lasso_error_t | lasso_data_service_get_answer ()
lasso_error_t | lasso_data_service_get_answers ()
lasso_error_t | lasso_data_service_get_answers_by_select ()
lasso_error_t | lasso_data_service_get_answers_by_item_id ()
lasso_error_t | lasso_data_service_init_modify ()
lasso_error_t | lasso_data_service_add_modification ()
lasso_error_t | lasso_data_service_process_modify_response_msg ()
lasso_error_t | lasso_data_service_process_request_msg ()
lasso_error_t | lasso_data_service_validate_request ()
lasso_error_t | lasso_data_service_build_query_response_msg ()
lasso_error_t | lasso_data_service_get_query_item ()
void | lasso_data_service_set_resource_data ()
xmlNode * | lasso_data_service_get_resource_data ()

## Types and Values

struct | LassoDataService

## 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.

## Functions

### lasso_data_service_new ()

    LassoDataService *
    lasso_data_service_new (LassoServer *server);

Creates a new LassoDataService.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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);

#### Parameters

service | a LassoDataService object |
message | a C string containing the SOAP request |
security_mech_id | a C string describing the required security mechanism or NULL. | [allow-none]

#### 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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

service | a LassoDataService object |

#### Returns

a newly allocated xmlNode or NULL.

[transfer full][allow-none]

## Types and Values

### struct LassoDataService

    struct LassoDataService {
    	LassoWsfProfile parent;
    };