LassoWsfProfile

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

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    struct              LassoWsfProfile;
    LassoIdentity *     lasso_wsf_profile_get_identity      (const LassoWsfProfile *profile);
    LassoSession *      lasso_wsf_profile_get_session       (const LassoWsfProfile *profile);
    gboolean            lasso_wsf_profile_is_identity_dirty (const LassoWsfProfile *profile);
    gboolean            lasso_wsf_profile_is_session_dirty  (const LassoWsfProfile *profile);
    lasso_error_t       lasso_wsf_profile_set_identity_from_dump
                                                            (LassoWsfProfile *profile,
                                                             const gchar *dump);
    lasso_error_t       lasso_wsf_profile_set_session_from_dump
                                                            (LassoWsfProfile *profile,
                                                             const gchar *dump);
    lasso_error_t       lasso_wsf_profile_build_soap_request_msg
                                                            (LassoWsfProfile *profile);
    lasso_error_t       lasso_wsf_profile_build_soap_response_msg
                                                            (LassoWsfProfile *profile);
    lasso_error_t       lasso_wsf_profile_init_soap_request (LassoWsfProfile *profile,
                                                             LassoNode *request);
    lasso_error_t       lasso_wsf_profile_init_soap_response
                                                            (LassoWsfProfile *profile,
                                                             LassoNode *response);
    lasso_error_t       lasso_wsf_profile_process_soap_request_msg
                                                            (LassoWsfProfile *profile,
                                                             const gchar *message,
                                                             const gchar *security_mech_id);
    lasso_error_t       lasso_wsf_profile_process_soap_response_msg
                                                            (LassoWsfProfile *profile,
                                                             const gchar *message);
    LassoWsfProfile *   lasso_wsf_profile_new               (LassoServer *server);
    LassoWsfProfile *   lasso_wsf_profile_new_full          (LassoServer *server,
                                                             LassoDiscoResourceOffering *offering);
    lasso_error_t       lasso_wsf_profile_set_description_from_offering
                                                            (LassoWsfProfile *profile,
                                                             const LassoDiscoResourceOffering *offering,
                                                             const char *security_mech_id);
    void                lasso_wsf_profile_set_description   (LassoWsfProfile *profile,
                                                             LassoDiscoDescription *description);
    LassoDiscoDescription * lasso_wsf_profile_get_description
                                                            (const LassoWsfProfile *profile);
    LassoDiscoResourceOffering * lasso_wsf_profile_get_resource_offering
                                                            (LassoWsfProfile *profile);
    lasso_error_t       lasso_wsf_profile_set_security_mech_id
                                                            (LassoWsfProfile *profile,
                                                             const char *security_mech_id);
    const char *        lasso_wsf_profile_get_security_mech_id
                                                            (LassoWsfProfile *profile);
    lasso_error_t       lasso_wsf_profile_init              (LassoWsfProfile *profile,
                                                             LassoServer *server,
                                                             LassoDiscoResourceOffering *offering);
    lasso_error_t       lasso_wsf_profile_get_remote_provider
                                                            (LassoWsfProfile *wsf_profile,
                                                             LassoProvider **provider);
    const char *        lasso_wsf_profile_get_remote_provider_id
                                                            (LassoWsfProfile *wsf_profile);
    LassoSoapFault *    lasso_wsf_profile_get_soap_fault    (LassoWsfProfile *wsf_profile);
    lasso_error_t       lasso_wsf_profile_set_soap_fault    (LassoWsfProfile *wsf_profile,
                                                             LassoSoapFault *soap_fault);
    lasso_error_t       lasso_wsf_profile_set_status_code   (LassoWsfProfile *wsf_profile,
                                                             const char *code);
    const char *        lasso_wsf_profile_get_status_code   (LassoWsfProfile *wsf_profile);
    lasso_error_t       lasso_wsf_profile_set_msg_url_from_description
                                                            (LassoWsfProfile *wsf_profile);
    void                lasso_wsf_profile_set_resource_offering
                                                            (LassoWsfProfile *profile,
                                                             LassoDiscoResourceOffering *offering);
    lasso_error_t       lasso_wsf_profile_init_interaction_service_redirect
                                                            (LassoWsfProfile *profile,
                                                             char *redirect_url);

## Description

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

## Details

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

### lasso_wsf_profile_get_identity ()

    LassoIdentity *     lasso_wsf_profile_get_identity      (const LassoWsfProfile *profile);

Gets the identity bound to `profile`.

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

`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).

`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).

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

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

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

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.

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

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

`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

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

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

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

Create a new WsfProfile with the given LassoServer object.

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

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

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

Setup the LassoWsfProfile for a given security mechanism.

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

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

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

`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"

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

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

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

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

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

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

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

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

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