LassoWsfProfile: Lasso Reference Manual

## LassoWsfProfile LassoWsfProfile — Base class for ID-WSF 1.0 services |

## Stability Level

Unstable, unless otherwise indicated

## Functions

LassoIdentity * | lasso_wsf_profile_get_identity ()
LassoSession * | lasso_wsf_profile_get_session ()
gboolean | lasso_wsf_profile_is_identity_dirty ()
gboolean | lasso_wsf_profile_is_session_dirty ()
lasso_error_t | lasso_wsf_profile_set_identity_from_dump ()
lasso_error_t | lasso_wsf_profile_set_session_from_dump ()
lasso_error_t | lasso_wsf_profile_build_soap_request_msg ()
lasso_error_t | lasso_wsf_profile_build_soap_response_msg ()
lasso_error_t | lasso_wsf_profile_init_soap_request ()
lasso_error_t | lasso_wsf_profile_init_soap_response ()
lasso_error_t | lasso_wsf_profile_process_soap_request_msg ()
lasso_error_t | lasso_wsf_profile_process_soap_response_msg ()
LassoWsfProfile * | lasso_wsf_profile_new ()
LassoWsfProfile * | lasso_wsf_profile_new_full ()
lasso_error_t | lasso_wsf_profile_set_description_from_offering ()
void | lasso_wsf_profile_set_description ()
LassoDiscoDescription * | lasso_wsf_profile_get_description ()
LassoDiscoResourceOffering * | lasso_wsf_profile_get_resource_offering ()
lasso_error_t | lasso_wsf_profile_set_security_mech_id ()
const char * | lasso_wsf_profile_get_security_mech_id ()
lasso_error_t | lasso_wsf_profile_init ()
lasso_error_t | lasso_wsf_profile_get_remote_provider ()
const char * | lasso_wsf_profile_get_remote_provider_id ()
LassoSoapFault * | lasso_wsf_profile_get_soap_fault ()
lasso_error_t | lasso_wsf_profile_set_soap_fault ()
lasso_error_t | lasso_wsf_profile_set_status_code ()
const char * | lasso_wsf_profile_get_status_code ()
lasso_error_t | lasso_wsf_profile_set_msg_url_from_description ()
void | lasso_wsf_profile_set_resource_offering ()
lasso_error_t | lasso_wsf_profile_init_interaction_service_redirect ()

## Types and Values

struct | LassoWsfProfile

## Description

Use this class to base your ID-WSF 1.0 services.

## Functions

### lasso_wsf_profile_get_identity ()

    LassoIdentity *
    lasso_wsf_profile_get_identity (const LassoWsfProfile *profile);

`lasso_wsf_profile_get_identity` is deprecated and should not be used in newly-written code.

Gets the identity bound to `profile` .

#### Parameters

profile | a LassoWsfProfile |

#### Returns

the identity or NULL if it none was found. The LassoIdentity object is internally allocated and must not be freed by the caller.

[transfer none][allow-none]

### lasso_wsf_profile_get_session ()

    LassoSession *
    lasso_wsf_profile_get_session (const LassoWsfProfile *profile);

Gets the session bound to `profile` .

#### Parameters

profile | a LassoWsfProfile |

#### Returns

the session or NULL if it none was found. The LassoSession object is internally allocated and must not be freed by the caller.

[transfer none][allow-none]

### lasso_wsf_profile_is_identity_dirty ()

    gboolean
    lasso_wsf_profile_is_identity_dirty (const LassoWsfProfile *profile);

Checks whether identity has been modified (and should therefore be saved).

#### Parameters

profile | a LassoWsfProfile |

#### Returns

`TRUE` if identity has changed

### lasso_wsf_profile_is_session_dirty ()

    gboolean
    lasso_wsf_profile_is_session_dirty (const LassoWsfProfile *profile);

Checks whether session has been modified (and should therefore be saved).

#### Parameters

profile | a LassoWsfProfile |

#### Returns

`TRUE` if session has changed

### lasso_wsf_profile_set_identity_from_dump ()

    lasso_error_t
    lasso_wsf_profile_set_identity_from_dump
                                   (LassoWsfProfile *profile,
                                    const gchar *dump);

Builds a new LassoIdentity object from XML dump and binds it to `profile` .

#### Parameters

profile | a LassoWsfProfile |
dump | XML identity dump |

#### Returns

0 on success; or a negative value otherwise.

### lasso_wsf_profile_set_session_from_dump ()

    lasso_error_t
    lasso_wsf_profile_set_session_from_dump
                                   (LassoWsfProfile *profile,
                                    const gchar *dump);

Builds a new LassoSession object from XML dump and binds it to `profile` .

#### Parameters

profile | a LassoWsfProfile |
dump | XML session dump |

#### Returns

0 on success; or a negative value otherwise.

### lasso_wsf_profile_build_soap_request_msg ()

    lasso_error_t
    lasso_wsf_profile_build_soap_request_msg
                                   (LassoWsfProfile *profile);

`lasso_wsf_profile_build_soap_request_msg` is deprecated and should not be used in newly-written code.

Create the char* string containing XML document for the SOAP ID-WSF request and eventually sign with the local public depending on the security mechanism requested.

#### Parameters

profile | the LassoWsfProfile object |

#### Returns

0 if construction is successfull.

### lasso_wsf_profile_build_soap_response_msg ()

    lasso_error_t
    lasso_wsf_profile_build_soap_response_msg
                                   (LassoWsfProfile *profile);

Create the char* string containing XML document for the SOAP ID-WSF response.

#### Parameters

wsf_profile | a LassoWsfProfile object |

#### Returns

0 if construction is successfull.

### lasso_wsf_profile_init_soap_request ()

    lasso_error_t
    lasso_wsf_profile_init_soap_request (LassoWsfProfile *profile,
                                         LassoNode *request);

Build the SOAP envelope for a request to and ID-WSF 1.0 web service and set the body of the request to request. The reference to request is not stolen i.e the ref count of request is increased by one after this call.

#### Parameters

profile | a LassoWsfProfile to initialize for a SOAP request |
request | a LassoNode object containing the body for the SOAP request, can be NULL. |

#### Returns

0 if initialization was successfull.

### lasso_wsf_profile_init_soap_response ()

    lasso_error_t
    lasso_wsf_profile_init_soap_response (LassoWsfProfile *profile,
                                          LassoNode *response);

Build a new SOAP envelope containing response to current SOAP request

#### Parameters

profile | a LassoWsfProfile object |
response | a LassoNode object |

### lasso_wsf_profile_process_soap_request_msg ()

    lasso_error_t
    lasso_wsf_profile_process_soap_request_msg
                                   (LassoWsfProfile *profile,
                                    const gchar *message,
                                    const gchar *security_mech_id);

Process an ID-WSF SOAP request, extract headers information, and check compliance with the security mechanism.

#### Parameters

profile | a LassoWsfProfile object |
message | a SOAP request message string |
security_mech_id | the security mechanism to apply |

#### Returns

0 if successful, an error code otherwise.

### lasso_wsf_profile_process_soap_response_msg ()

    lasso_error_t
    lasso_wsf_profile_process_soap_response_msg
                                   (LassoWsfProfile *profile,
                                    const gchar *message);

Parse a SOAP response from an ID-WSF 1.0 service, eventually signal a SOAP fault.

#### Parameters

profile | a LassoWsfProfile object |
message | the textual representaition of a SOAP message |

#### Returns

0 if the processing of this message was successful.

### lasso_wsf_profile_new ()

    LassoWsfProfile *
    lasso_wsf_profile_new (LassoServer *server);

`lasso_wsf_profile_new` is deprecated and should not be used in newly-written code.

Create a new WsfProfile with the given LassoServer object.

Return: a new LassoWsfProfile if creation and initialization were successfull, NULL otherwise.

#### Parameters

server | a LassoServer object to lookup remote provider informations |

### lasso_wsf_profile_new_full ()

    LassoWsfProfile *
    lasso_wsf_profile_new_full (LassoServer *server,
                                LassoDiscoResourceOffering *offering);

Create a new WsfProfile with the given LassoServer object and the given LassoDiscoResourceOffering.

Return: a new LassoWsfProfile if creation and initialization were successfull, NULL otherwise.

#### Parameters

server | a LassoServer object to lookup remote provider informations. |
offering | a LassoDiscoResourceOffering for the requested service. |

### lasso_wsf_profile_set_description_from_offering ()

    lasso_error_t
    lasso_wsf_profile_set_description_from_offering
                                   (LassoWsfProfile *profile,
                                    const LassoDiscoResourceOffering *offering,
                                    const char *security_mech_id);

`lasso_wsf_profile_set_description_from_offering` is deprecated and should not be used in newly-written code.

Setup the LassoWsfProfile for a given security mechanism.

#### Parameters

profile | a LassoWsfProfile |
offering | a LassoDiscoResourceOffering containing descriptions |
security_mech_id | an URL representing the wished security mechanism, if NULL take the first descriptions |

#### Returns

0 if a corresponding description was found, LASSO_PROFILE_ERROR_MISSING_SERVICE_DESCRIPTION if no description with the given security mechanism was found.

### lasso_wsf_profile_set_description ()

    void
    lasso_wsf_profile_set_description (LassoWsfProfile *profile,
                                       LassoDiscoDescription *description);

Set the currently registered LassoDiscoDescription, that permits to locate the endpoint and the security mechanism to use for the next ID-WSF request.

#### Parameters

profile | the LassoWsfProfile |
description | a LassoDiscoDescription |

### lasso_wsf_profile_get_description ()

    LassoDiscoDescription *
    lasso_wsf_profile_get_description (const LassoWsfProfile *profile);

Returns the currently registered LassoDiscoDescription, that permits to locate the endpoint and the security mechanism to use for the next ID-WSF request.

#### Parameters

profile | a LassoWsfProfile |

#### Returns

a LassoDiscoDescriptio or NULL if none is present.

[transfer full]

### lasso_wsf_profile_get_resource_offering ()

    LassoDiscoResourceOffering *
    lasso_wsf_profile_get_resource_offering
                                   (LassoWsfProfile *profile);

Returns the ResourceOffering setupt with this profile object.

#### Parameters

profile | the LassoWsfProfile object |

#### Returns

a LassoDiscoResourceOffering if one was setup during construction, NULL otherwise.

[transfer full]

### lasso_wsf_profile_set_security_mech_id ()

    lasso_error_t
    lasso_wsf_profile_set_security_mech_id
                                   (LassoWsfProfile *profile,
                                    const char *security_mech_id);

Set the security mechanism to use. Currently only SAML and NULL mechanism are supported for authentication. Transport is not handled by lasso so all are supported.

List of supported mechanism ids: LASSO_SECURITY_MECH_NULL or "urn:liberty:security:2003-08:null:null" LASSO_SECURITY_MECH_SAML or "urn:liberty:security:2003-08:null:SAML" LASSO_SECURITY_MECH_TLS or "urn:liberty:security:2003-08:TLS:null" LASSO_SECURITY_MECH_TLS_SAML or "urn:liberty:security:2003-08:TLS:SAML" LASSO_SECURITY_MECH_CLIENT_TLS or "urn:liberty:security:2003-08:ClientTLS:null" LASSO_SECURITY_MECH_CLIENT_TLS_SAML or "urn:liberty:security:2003-08:ClientTLS:SAML"

#### Parameters

profile | the LassoWsfProfile object |
security_mech_id | a char* string representing the chosen security mech id. |

#### Returns

0 if the security mechanism is supported by this LassoWsfProfile object, an error code otherwise.

### lasso_wsf_profile_get_security_mech_id ()

    const char *
    lasso_wsf_profile_get_security_mech_id
                                   (LassoWsfProfile *profile);

#### Parameters

profile | the LassoWsfProfile object |

#### Returns

the current security mechanism id for this object.

[transfer none]

### lasso_wsf_profile_init ()

    lasso_error_t
    lasso_wsf_profile_init (LassoWsfProfile *profile,
                            LassoServer *server,
                            LassoDiscoResourceOffering *offering);

Initialize a LassoWsfProfile in order to handle or send request to, an ID-WSF web service.

Return: 0 if initialization was successfull.

#### Parameters

profile | the LassoWsfProfile to initialize |
server | a LassoServer object to resolve provider IDs. |
offering | a LassoDiscoResourceOffering for the targetted web service. |

### lasso_wsf_profile_get_remote_provider ()

    lasso_error_t
    lasso_wsf_profile_get_remote_provider (LassoWsfProfile *wsf_profile,
                                           LassoProvider **provider);

Return the remote provider parsed in the last processing of a SOAP request or a SOAP response.

#### Parameters

wsf_profile | a LassoWsfProfile object |
provider | an output pointer to LassoProvider object variable. | [transfer full]

#### Returns

0 if successfull, LASSO_PROFILE_ERROR_MISSING_REMOTE_PROVIDERID if no provider id is present in the SOAP headers, or LASSO_SERVER_ERROR_PROVIDER_NOT_FOUND if the provider is unknown to us.

### lasso_wsf_profile_get_remote_provider_id ()

    const char *
    lasso_wsf_profile_get_remote_provider_id
                                   (LassoWsfProfile *wsf_profile);

Return the remote provider id parsed in the last processing of a SOAP request or a SOAP response.

#### Parameters

wsf_profile | a LassoWsfProfile object |

#### Returns

the provider id string or NULL.

[transfer none][allow-none]

### lasso_wsf_profile_get_soap_fault ()

    LassoSoapFault *
    lasso_wsf_profile_get_soap_fault (LassoWsfProfile *wsf_profile);

### lasso_wsf_profile_set_soap_fault ()

    lasso_error_t
    lasso_wsf_profile_set_soap_fault (LassoWsfProfile *wsf_profile,
                                      LassoSoapFault *soap_fault);

Set a SOAP fault to be returned in next SOAP response message. The SOAP fault is removed by lasso_wsf_profile_init_soap_request.

#### Parameters

wsf_profile | a LassoWsfProfile object |
soap_fault | a LassoSoapFault object |

#### Returns

0 if successful, an error code otherwise.

### lasso_wsf_profile_set_status_code ()

    lasso_error_t
    lasso_wsf_profile_set_status_code (LassoWsfProfile *wsf_profile,
                                       const char *code);

Set the status code to set in the next built response.

#### Parameters

wsf_profile | a LassoWsfProfile |
status_code | a string representing the status code |

#### Returns

0 if successful, an error code otherwise.

### lasso_wsf_profile_get_status_code ()

    const char *
    lasso_wsf_profile_get_status_code (LassoWsfProfile *wsf_profile);

Return the actual status code for this protocol object.

#### Parameters

wsf_profile | a LassoWsfProfile object |

#### Returns

a string owned by the profile object or NULL.

[transfer none][allow-none]

### lasso_wsf_profile_set_msg_url_from_description ()

    lasso_error_t
    lasso_wsf_profile_set_msg_url_from_description
                                   (LassoWsfProfile *wsf_profile);

### lasso_wsf_profile_set_resource_offering ()

    void
    lasso_wsf_profile_set_resource_offering
                                   (LassoWsfProfile *profile,
                                    LassoDiscoResourceOffering *offering);

Set the Resssource Offering to setup this ID-WSF profile.

#### Parameters

profile | a LassoWsfProfile |
offering | a LassoDiscoResourceOffering |

### lasso_wsf_profile_init_interaction_service_redirect ()

    lasso_error_t
    lasso_wsf_profile_init_interaction_service_redirect
                                   (LassoWsfProfile *profile,
                                    char *redirect_url);

## Types and Values

### struct LassoWsfProfile

    struct LassoWsfProfile {
    	LassoNode parent;

    	LassoServer *server;

    	LassoNode *request;
    	LassoNode *response;

    	LassoSoapEnvelope *soap_envelope_request;
    	LassoSoapEnvelope *soap_envelope_response;

    	gchar *msg_url;
    	gchar *msg_body;
    };