libinfinity-0.6 Reference Manual: InfcRequestManager

## InfcRequestManager InfcRequestManager — Keeps track of pending asynchronous requests |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfcRequestManagerForeachFunc) ()
InfcRequestManager * | infc_request_manager_new ()
InfcRequest * | infc_request_manager_add_request ()
InfcRequest * | infc_request_manager_add_request_valist ()
void | infc_request_manager_remove_request ()
void | infc_request_manager_finish_request ()
void | infc_request_manager_fail_request ()
void | infc_request_manager_clear ()
InfcRequest * | infc_request_manager_get_request_by_seq ()
InfcRequest * | infc_request_manager_get_request_by_xml ()
InfcRequest * | infc_request_manager_get_request_by_xml_required ()
void | infc_request_manager_foreach_request ()
void | infc_request_manager_foreach_named_request ()

## Properties

guint | sequence-id | Read / Write / Construct Only

## Signals

void | request-add | Run Last
void | request-remove | Run Last

## Types and Values

struct | InfcRequestManager
struct | InfcRequestManagerClass

## Object Hierarchy

        GObject
        ╰── InfcRequestManager

## Includes

    #include <libinfinity/client/infc-request-manager.h>

## Description

This class keeps track of requests sent by InfcBrowser and InfcSessionProxy (typically via the InfBrowser and InfSessionProxy APIs). It is used internally by InfcBrowser and InfcSessionProxy, and usually end-users of the libinfinity API do not need to use this class directly.

Requests can be added with the `infc_request_manager_add_request()` and `infc_request_manager_add_request_valist()` methods and retrieved back via their unique seq number with `infc_request_manager_get_request_by_seq()`. In addition to this basic API, there are various convenience functions available as well.

## Functions

### InfcRequestManagerForeachFunc ()

    void
    (*InfcRequestManagerForeachFunc) (InfcRequest *request,
                                      gpointer user_data);

This signature specifies the callback type when iterating over all requests of the request manager.

#### Parameters

request | The current request. |
user_data | Additional data passed to `infc_request_manager_foreach_request()` or `infc_request_manager_foreach_named_request()`. |

### infc_request_manager_new ()

    InfcRequestManager *
    infc_request_manager_new (guint seq_id);

Creates a new InfcRequestManager.

#### Parameters

seq_id | The local sequence ID. |

#### Returns

A newly allocated InfcRequestManager.

### infc_request_manager_add_request ()

    InfcRequest *
    infc_request_manager_add_request (InfcRequestManager *manager,
                                      GType request_type,
                                      const gchar *request_name,
                                      GCallback callback,
                                      gpointer user_data,
                                      const gchar *first_property_name,
                                      ...);

Adds a request to the request manager. A new signal handler for the request's "finished" signal will be installed and made to invoke the given callback.

#### Parameters

manager | A InfcRequestManager. |
request_type | The type of request to add, such as InfcProgressRequest. |
request_name | The name of the request, such as "explore-node" or "subscribe-session". |
callback | A GCallback that will be called when the request has completed, or `NULL`. |
user_data | Additional data passed to the callback. |
first_property_name | The first property name apart from name and seq to set for the new request. |
... | The value of the first property, followed optionally by more name/value pairs, followed by `NULL`. |

#### Returns

The generated InfcRequest (actually of type `request_type` ).

### infc_request_manager_add_request_valist ()

    InfcRequest *
    infc_request_manager_add_request_valist
                                   (InfcRequestManager *manager,
                                    GType request_type,
                                    const gchar *request_name,
                                    GCallback callback,
                                    gpointer user_data,
                                    const gchar *first_property_name,
                                    va_list arglist);

Adds a request to the request manager. A new signal handler for the request's "finished" signal will be installed and made to invoke the given callback.

#### Parameters

manager | A InfcRequestManager. |
request_type | The type of request to add, such as InfcProgressRequest. |
request_name | The name of the request, such as "explore-node" or "subscribe-session" |
callback | A GCallback that will be called when the request has completed, or `NULL`. |
user_data | Additional data passed to the callback. |
first_property_name | The first property name apart from name and seq to set for the new request. |
arglist | The value of the first property, followed optionally by more name/value pairs, followed by `NULL`. |

#### Returns

The generated InfcRequest (actually of type `request_type` ).

### infc_request_manager_remove_request ()

    void
    infc_request_manager_remove_request (InfcRequestManager *manager,
                                         InfcRequest *request);

Removes a request from the request manager.

#### Parameters

manager | A InfcRequestManager. |
request | A InfcRequest that has previously been added to `manager` . |

### infc_request_manager_finish_request ()

    void
    infc_request_manager_finish_request (InfcRequestManager *manager,
                                         InfcRequest *request,
                                         InfRequestResult *result);

Marks `request` as finished using `inf_request_finish()` and then removes the request from the manager. The function takes ownership of `result` .

#### Parameters

manager | A InfcRequestManager. |
request | A InfcRequest that has previously been added to `manager` . |
result | The request result. |

### infc_request_manager_fail_request ()

    void
    infc_request_manager_fail_request (InfcRequestManager *manager,
                                       InfcRequest *request,
                                       GError *error);

Marks `request` as failed using `inf_request_fail()` and then removes the request from the manager.

#### Parameters

manager | A InfcRequestManager. |
request | A InfcRequest that has previously been added to `manager` . |
error | Error information why the request failed. |

### infc_request_manager_clear ()

    void
    infc_request_manager_clear (InfcRequestManager *manager);

Removes all the requests in `manager` .

#### Parameters

manager | A InfcRequestManager. |

### infc_request_manager_get_request_by_seq ()

    InfcRequest *
    infc_request_manager_get_request_by_seq
                                   (InfcRequestManager *manager,
                                    guint seq);

Returns a previously-added request that has the given seq.

#### Parameters

manager | A InfcRequestManager. |
seq | The sequence number to which the request should be retrieved. |

#### Returns

The request with the given seq, or `NULL` if there is no such request.

### infc_request_manager_get_request_by_xml ()

    InfcRequest *
    infc_request_manager_get_request_by_xml
                                   (InfcRequestManager *manager,
                                    const gchar *name,
                                    xmlNodePtr xml,
                                    GError **error);

Looks whether there is a "seq" attribute in `xml` . If not, the function returns `NULL` (without setting `error` ). Otherwise, it returns the request with the given seq and name, if the sequence ID matches. If the "seq" attribute is set but the actual request is not present (or has another name), the function returns `NULL` and `error` is set.

#### Parameters

manager | A InfcRequestManager. |
name | Name of the expected request. May be `NULL` to allow all requests. |
xml | XML node that is supposed to contain a "seq" attribute. |
error | Location to store error information. |

#### Returns

The resulting request, or `NULL` if the "seq" attribute was not present or an error occured.

### infc_request_manager_get_request_by_xml_required ()

    InfcRequest *
    infc_request_manager_get_request_by_xml_required
                                   (InfcRequestManager *manager,
                                    const gchar *name,
                                    xmlNodePtr xml,
                                    GError **error);

Looks whether there is a "seq" attribute in `xml` . If so, it returns the request with the given seq and name, if the sequence ID matches. If the "seq" attribute is not set or the actual request is not present (or has another name), the function returns `NULL` and `error` is set.

#### Parameters

manager | A InfcRequestManager. |
name | Name of the expected request. May be `NULL` to allow all requests. |
xml | XML node that is supposed to contain a "seq" attribute. |
error | Location to store error information. |

#### Returns

The resulting request, or `NULL` if an error occured.

### infc_request_manager_foreach_request ()

    void
    infc_request_manager_foreach_request (InfcRequestManager *manager,
                                          InfcRequestManagerForeachFunc func,
                                          gpointer user_data);

Calls the given function for each request that has been added to the request manager.

#### Parameters

manager | A InfcRequestManager. |
func | The function to be called. |
user_data | Arbitrary data to be passed to `func` . |

### infc_request_manager_foreach_named_request ()

    void
    infc_request_manager_foreach_named_request
                                   (InfcRequestManager *manager,
                                    const gchar *name,
                                    InfcRequestManagerForeachFunc func,
                                    gpointer user_data);

Calls the given function for each request that has been added to the request manager that has the name `name` .

#### Parameters

manager | A InfcRequestManager. |
name | The name of the request to look for. |
func | The function to be called. |
user_data | Arbitrary data to be passed to `func` . |

## Types and Values

### struct InfcRequestManager

    struct InfcRequestManager;

InfcRequestManager is an opaque data type. You should only access it via the public API functions.

### struct InfcRequestManagerClass

    struct InfcRequestManagerClass {
      void (*request_add)(InfcRequestManager* manager,
                          InfcRequest* request);
      void (*request_remove)(InfcRequestManager* manager,
                             InfcRequest* request);
    };

This structure contains the default signal handlers of the InfcRequestManager class.

#### Members

`request_add` () | Default signal handler for the “request-add” signal. |
`request_remove` () | Default signal handler for the “request-remove” signal. |

## Property Details

### The `“sequence-id”` property

      “sequence-id”              guint

The local sequence identifier.

Flags: Read / Write / Construct Only

Default value: 0

## Signal Details

### The `“request-add”` signal

    void
    user_function (InfcRequestManager *manager,
                   InfcRequest        *request,
                   gpointer            user_data)

This signal is emitted whenever a request was added to the request manager.

#### Parameters

manager | The InfcRequestManager emitting the signal. |
request | The InfcRequest that was added. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“request-remove”` signal

    void
    user_function (InfcRequestManager *manager,
                   InfcRequest        *request,
                   gpointer            user_data)

This signal is emitted whenever a request was removed from the request manager. Typically this happens when the request has finished (either successfully or unsuccessfully). It can also happen when the client is disconnected from the server while a request was still pending.

#### Parameters

manager | The InfcRequestManager emitting the signal. |
request | The InfcRequest that was removed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

InfRequest, InfcRequest, InfcBrowser, InfcSessionProxy