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:

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:(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.

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