LassoDiscovery: Lasso Reference Manual

## LassoDiscovery LassoDiscovery — ID-WSF Discovery Service Profile |

## Functions

LassoDiscovery * | lasso_discovery_new ()
LassoDiscovery * | lasso_discovery_new_full ()
lasso_error_t | lasso_discovery_init_modify ()
lasso_error_t | lasso_discovery_add_insert_entry ()
lasso_error_t | lasso_discovery_add_remove_entry ()
lasso_error_t | lasso_discovery_init_query ()
lasso_error_t | lasso_discovery_add_requested_service_type ()
lasso_error_t | lasso_discovery_process_request_msg ()
lasso_error_t | lasso_discovery_build_response_msg ()
lasso_error_t | lasso_discovery_process_modify_response_msg ()
lasso_error_t | lasso_discovery_process_query_response_msg ()
LassoWsfProfile * | lasso_discovery_get_service ()
GList * | lasso_discovery_get_services ()
LassoWsfProfile * | (*LassoWsfProfileConstructor) ()
void | lasso_discovery_register_constructor_for_service_type ()
void | lasso_discovery_unregister_constructor_for_service_type ()

## Types and Values

struct | LassoDiscovery

## Description

The Discovery service usually runs on the principal identity provider and knowns about resources and services related to the principal. Attribute providers can register themselves as offering resources for an user while other services can ask where to find a given resource.

The following example is a service provider asking for a "PP" service (an attribute provider for the "Personal Profile"):

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    LassoServer *server;  // initialized before
    char* session_dump;   // initialized before

    LassoDiscovery *discovery;    // discovery service
    char *soap_answer;            // SOAP answer from disco service
    LassoProfileService *service; // instance to perform on requested service

    discovery = lasso_discovery_new(server);
    lasso_wsf_profile_set_session_from_dump(LASSO_WSF_PROFILE(discovery), session_dump);
    lasso_discovery_init_query(discovery);
    lasso_discovery_add_requested_service(discovery, LASSO_PP10_HREF);
    lasso_discovery_build_request_msg(discovery);

    // service must perform SOAP call to LASSO_WSF_PROFILE(discovery)->msg_url
    // the SOAP message is LASSO_WSF_PROFILE(discovery)->msg_body.  The answer
    // is stored in char* soap_answer;

    lasso_discovery_process_query_response_msg(discovery, soap_answer);

    // get an object to access the first service returned, or NULL if an error happened
    service = lasso_discovery_get_service(discovery);

## Functions

### lasso_discovery_new ()

    LassoDiscovery *
    lasso_discovery_new (LassoServer *server);

Creates a new LassoDiscovery.

#### Parameters

server | the LassoServer |

#### Returns

a newly created LassoDiscovery object; or NULL if an error occured.

### lasso_discovery_new_full ()

    LassoDiscovery *
    lasso_discovery_new_full (LassoServer *server,
                              LassoDiscoResourceOffering *offering);

Creates a new LassoDiscovery.

#### Parameters

server | the LassoServer |
offering | the LassoDiscoResourceOffering |

#### Returns

a newly created LassoDiscovery object; or NULL if an error occured.

### lasso_discovery_init_modify ()

    lasso_error_t
    lasso_discovery_init_modify (LassoDiscovery *discovery,
                                 const char *security_mech_id);

Initializes a disco Modify/InsertEntry

#### Parameters

discovery | a LassoDiscovery |
security_mech_id | the security mechanism identifier. | [allow-none]

#### Returns

0 on success; an error code otherwise.

### lasso_discovery_add_insert_entry ()

    lasso_error_t
    lasso_discovery_add_insert_entry (LassoDiscovery *discovery,
                                      LassoDiscoServiceInstance *serviceInstance,
                                      LassoDiscoResourceID *resourceId);

Add an LassoDiscoInsertEntry containing a new LassoDiscoResourceOffering, and initialize the LassoDiscoResourceOffering using the LassoDiscoServiceInstance and LassoDiscoResourceId object.

#### Parameters

discovery | a LassoDiscovery object |
serviceInstance | an optional LassoDiscoServiceInstance object |
resourceID | the new LassoDiscoResourceID used to create the LassoDiscoResrouceOffering |

#### Returns

the newly created LassoDiscoInsertEntry or NULL if some preconditions failed.

### lasso_discovery_add_remove_entry ()

    lasso_error_t
    lasso_discovery_add_remove_entry (LassoDiscovery *discovery,
                                      const gchar *entryID);

Add a RemoveEntry to the current Modify message for a Discovery service, to remove the resource offering identified by entryID (returned in the response to a Modify/InsertEntry message).

#### Parameters

discovery | a LassoDiscovery object |
entryID | the idenitfier of a ResourceOffering to remove. |

#### Returns

0 if successful, an error code otherwise.

### lasso_discovery_init_query ()

    lasso_error_t
    lasso_discovery_init_query (LassoDiscovery *discovery,
                                const gchar *security_mech_id);

Initializes a disco:Query message.

#### Parameters

discovery | a LassoDiscovery |
security_mech_id | identifier of a wished security mechanism, or NULL if any is ok. | [allow-none]

#### Returns

0 on success; or a negative value otherwise.

### lasso_discovery_add_requested_service_type ()

    lasso_error_t
    lasso_discovery_add_requested_service_type
                                   (LassoDiscovery *discovery,
                                    const gchar *service_type,
                                    const gchar *option);

Adds a request for service of `service_type` to the disco:Query being built.

#### Parameters

discovery | a LassoDiscovery |
service_type | requested service type |
option | option to the requested service |

#### Returns

0 if successful

### lasso_discovery_process_request_msg ()

    lasso_error_t
    lasso_discovery_process_request_msg (LassoDiscovery *discovery,
                                         const gchar *message,
                                         const gchar *security_mech_id);

Process a received SOAP message for the discovery service.

#### Parameters

discovery | a LassoDiscovery object |
message | a serialized SOAP message |
security_mech_id | the security mech id to use for validating authorizations. | [allow-none]

#### Returns

0 if successfull, an error code otherwise.

### lasso_discovery_build_response_msg ()

    lasso_error_t
    lasso_discovery_build_response_msg (LassoDiscovery *discovery);

Execute needed action for the received request, and produce a response message.

If any critical error occur, it tries to produce a SOAP fault.

#### Parameters

discovery | a LassoDiscovery object |

#### Returns

0 on success; or an error code otherwise.

### lasso_discovery_process_modify_response_msg ()

    lasso_error_t
    lasso_discovery_process_modify_response_msg
                                   (LassoDiscovery *discovery,
                                    const gchar *message);

Processes a disco:ModifyResponse SOAP message.

#### Parameters

discovery | a LassoDiscovery |
message | the disco:ModifyResponse SOAP message |

#### Returns

0 on success; or a negative value otherwise.

### lasso_discovery_process_query_response_msg ()

    lasso_error_t
    lasso_discovery_process_query_response_msg
                                   (LassoDiscovery *discovery,
                                    const gchar *message);

Processes a disco:QueryResponse message. Extract credentials from the response and put them in the session, for later use by a request from a LassoWsfProfile.

#### Parameters

discovery | a LassoDiscovery |
message | the disco:QueryResponse message |

#### Returns

0 on success; or a negative value otherwise.

### lasso_discovery_get_service ()

    LassoWsfProfile *
    lasso_discovery_get_service (LassoDiscovery *discovery,
                                 const char *service_type);

After a disco:query message, creates a LassoDataService instance for the requested `service_type` with the first resource offering found or the first resource offering matching the service type.

#### Parameters

discovery | a LassoDiscovery |
service_type | the requested service type |

#### Returns

a newly created LassoDataService object; or NULL if an error occured.

[transfer full][allow-none]

### lasso_discovery_get_services ()

    GList *
    lasso_discovery_get_services (LassoDiscovery *discovery);

After a disco:query message, creates a GList object of LassoDataService.

#### Parameters

discovery | a LassoDiscovery |

#### Returns

a newly created GList object of LassoDataService; or NULL if an error occured.

[transfer full][element-type LassoNode]

### LassoWsfProfileConstructor ()

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

### lasso_discovery_register_constructor_for_service_type ()

    void
    lasso_discovery_register_constructor_for_service_type
                                   (gchar const *service_type,
                                    LassoWsfProfileConstructor constructor);

This function permits to subclass of LassoWsfProfile to register a constructor for the service type they supports.

#### Parameters

service_type | the URI of the service type |
constructor | a constructor function for the profile handling this service type |

### lasso_discovery_unregister_constructor_for_service_type ()

    void
    lasso_discovery_unregister_constructor_for_service_type
                                   (gchar const *service_type,
                                    LassoWsfProfileConstructor constructor);

This function permits to subclass of LassoWsfProfile to unregister a constructor for the service type they previously registered using `lasso_discovery_register_constructor_for_service_type()`.

#### Parameters

service_type | the URI of the service type |
constructor | a constructor function for the profile handling this service type |

## Types and Values

### struct LassoDiscovery

    struct LassoDiscovery {
    	LassoWsfProfile parent;

    	LassoDiscoResourceID *ResourceID;
    	LassoDiscoEncryptedResourceID *EncryptedResourceID;
    };