## InfAdoptedRequest InfAdoptedRequest — Request processed by InfAdoptedAlgorithm. |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/adopted/inf-adopted-request.h>

    enum                InfAdoptedRequestType;
                        InfAdoptedRequest;
    struct              InfAdoptedRequestClass;
    InfAdoptedRequest * inf_adopted_request_new_do          (InfAdoptedStateVector *vector,
                                                             guint user_id,
                                                             InfAdoptedOperation *operation);
    InfAdoptedRequest * inf_adopted_request_new_undo        (InfAdoptedStateVector *vector,
                                                             guint user_id);
    InfAdoptedRequest * inf_adopted_request_new_redo        (InfAdoptedStateVector *vector,
                                                             guint user_id);
    InfAdoptedRequest * inf_adopted_request_copy            (InfAdoptedRequest *request);
    InfAdoptedRequestType inf_adopted_request_get_request_type
                                                            (InfAdoptedRequest *request);
    InfAdoptedStateVector * inf_adopted_request_get_vector  (InfAdoptedRequest *request);
    guint               inf_adopted_request_get_user_id     (InfAdoptedRequest *request);
    InfAdoptedOperation * inf_adopted_request_get_operation (InfAdoptedRequest *request);
    guint               inf_adopted_request_get_index       (InfAdoptedRequest *request);
    gboolean            inf_adopted_request_need_concurrency_id
                                                            (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against);
    InfAdoptedConcurrencyId inf_adopted_request_get_concurrency_id
                                                            (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against);
    InfAdoptedRequest * inf_adopted_request_transform       (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against,
                                                             InfAdoptedConcurrencyId concurrency_id);
    InfAdoptedRequest * inf_adopted_request_mirror          (InfAdoptedRequest *request,
                                                             guint by);
    InfAdoptedRequest * inf_adopted_request_fold            (InfAdoptedRequest *request,
                                                             guint into,
                                                             guint by);
    gboolean            inf_adopted_request_affects_buffer  (InfAdoptedRequest *request);

## Object Hierarchy

      GEnum
       +----InfAdoptedRequestType

      GObject
       +----InfAdoptedRequest

## Properties

      "operation"                InfAdoptedOperation*  : Read / Write / Construct Only
      "type"                     InfAdoptedRequestType  : Read / Write / Construct Only
      "user-id"                  guint                 : Read / Write / Construct Only
      "vector"                   InfAdoptedStateVector*  : Read / Write / Construct Only

## Description

An InfAdoptedRequest is basically an InfAdoptedOperation with some metadata used by InfAdoptedAlgorithm to determine which operations to transform against each other. If the type of the request is `INF_ADOPTED_REQUEST_DO`, then it contains the operation to perform, otherwise it does not because the request does not know the operation, it is computed by InfAdoptedAlgorithm when required. A InfAdoptedRequest also contains the state in which the operation can be applied to the buffer and the user ID of the InfAdoptedUser having generated the request.

## Details

### enum InfAdoptedRequestType

    typedef enum {
      INF_ADOPTED_REQUEST_DO,
      INF_ADOPTED_REQUEST_UNDO,
      INF_ADOPTED_REQUEST_REDO
    } InfAdoptedRequestType;

Possible types for an InfAdoptedRequest.

`INF_ADOPTED_REQUEST_DO` | A request that performs an operation.
`INF_ADOPTED_REQUEST_UNDO` | A request that undoes a previously applied request.
`INF_ADOPTED_REQUEST_REDO` | A request that redoes a previously undone request.

### InfAdoptedRequest

    typedef struct _InfAdoptedRequest InfAdoptedRequest;

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

### struct InfAdoptedRequestClass

    struct InfAdoptedRequestClass {
    };

This structure does not contain any public fields.

### inf_adopted_request_new_do ()

    InfAdoptedRequest * inf_adopted_request_new_do          (InfAdoptedStateVector *vector,
                                                             guint user_id,
                                                             InfAdoptedOperation *operation);

Creates a new InfAdoptedRequest with type `INF_ADOPTED_REQUEST_DO`.

`vector` : | The vector time at which the request was made.
`user_id` : | The ID of the user that made the request.
`operation` : | The operation the user performed.
Returns : | A new DO request.

### inf_adopted_request_new_undo ()

    InfAdoptedRequest * inf_adopted_request_new_undo        (InfAdoptedStateVector *vector,
                                                             guint user_id);

Creates a new InfAdoptedRequest with type `INF_ADOPTED_REQUEST_UNDO`. The operation performed is implicitely defined by reverting the operation of the associated DO or REDO request, but must still be computed by InfAdoptedAlgorithm.

`vector` : | The vector time at which the request was made.
`user_id` : | The ID of the user that made the request.
Returns : | A new UNDO request.

### inf_adopted_request_new_redo ()

    InfAdoptedRequest * inf_adopted_request_new_redo        (InfAdoptedStateVector *vector,
                                                             guint user_id);

Creates a new InfAdoptedRequest with type `INF_ADOPTED_REQUEST_REDO`. The operation performed is implicitely defined by reverting the operation of the associated UNDO request, but must still be computed by InfAdoptedAlgorithm.

`vector` : | The vector time at which the request was made.
`user_id` : | The ID of the user that made the request.
Returns : | A new REDO request.

### inf_adopted_request_copy ()

    InfAdoptedRequest * inf_adopted_request_copy            (InfAdoptedRequest *request);

Creates a copy of `request` with an initial reference count of 1.

`request` : | The InfAdoptedRequest to copy.
Returns : | A new InfAdoptedRequest.

### inf_adopted_request_get_request_type ()

    InfAdoptedRequestType inf_adopted_request_get_request_type
                                                            (InfAdoptedRequest *request);

Returns the request type of `request`.

`request` : | A InfAdoptedRequest.
Returns : | The type of `request`.

### inf_adopted_request_get_vector ()

    InfAdoptedStateVector * inf_adopted_request_get_vector  (InfAdoptedRequest *request);

Returns the vector time the request was made i.e. its operation can be applied to the buffer.

`request` : | A InfAdoptedRequest.
Returns : | The state vector of `request`. The returned value should not be freed, it is owned by the InfAdoptedRequest.

### inf_adopted_request_get_user_id ()

    guint               inf_adopted_request_get_user_id     (InfAdoptedRequest *request);

Returns the user ID of the user that issued `request`.

`request` : | A InfAdoptedRequest.
Returns : | The request's user ID.

### inf_adopted_request_get_operation ()

    InfAdoptedOperation * inf_adopted_request_get_operation (InfAdoptedRequest *request);

Returns the operation carried by the request. This can only be called if the request's type is `INF_ADOPTED_REQUEST_DO`.

`request` : | A InfAdoptedRequest.
Returns : | The request's operation.

### inf_adopted_request_get_index ()

    guint               inf_adopted_request_get_index       (InfAdoptedRequest *request);

Returns the vector time component of the request's own users. This corresponds to the request index by that user.

`request` : | A InfAdoptedRequest.
Returns : | The vector time component of the request's own user.

### inf_adopted_request_need_concurrency_id ()

    gboolean            inf_adopted_request_need_concurrency_id
                                                            (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against);

Returns whether transforming `request` against `against` requires a concurrency ID. You can still call `inf_adopted_request_transform()` with a concurrency ID of `INF_ADOPTED_CONCURRENCY_NONE` even if this function returns `TRUE` if you don't have another possibility to find a concurrency ID in which case user IDs are used to determine which request to transform.

Both request need to be of type `INF_ADOPTED_REQUEST_DO`, and their state vectors must be the same.

`request` : | The request to transform.
`against` : | The request to transform against.
Returns : | Whether transformation of `request` against `against` requires a concurrency ID.

### inf_adopted_request_get_concurrency_id ()

    InfAdoptedConcurrencyId inf_adopted_request_get_concurrency_id
                                                            (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against);

Returns a concurrency ID for transformation of `operation` against `against`. It always returns `INF_ADOPTED_CONCURRENCY_NONE` when `inf_adopted_request_need_concurrency_id()` returns `TRUE` (but that's not necessarily true the other way around), since it is not possible to decide which operation to transform without any additional information.

However, the function can be called on the same requests in a previous state. In some cases, a decision can be made based on these previous requests. This can be used as a concurrency ID for a call to `inf_adopted_request_transform()`. If this does not yield a decision, it is still possible to call `inf_adopted_request_transform()` with `INF_ADOPTED_CONCURRENCY_NONE` as concurrency ID in which case an arbitrary request will be transformed, based on the user IDs of the requests.

Both requests must be of type `INF_ADOPTED_REQUEST_DO`, and their state vectors must be the same.

`request` : | The request to transform.
`against` : | The request to transform against.
Returns : | A concurrency ID between `operation` and `against`. Can be `INF_ADOPTED_CONCURRENCY_NONE` in case no decision can be made.

### inf_adopted_request_transform ()

    InfAdoptedRequest * inf_adopted_request_transform       (InfAdoptedRequest *request,
                                                             InfAdoptedRequest *against,
                                                             InfAdoptedConcurrencyId concurrency_id);

Transforms the operation of `request` against the operation of `against`. Both requests must be of type `INF_ADOPTED_REQUEST_DO`, and their state vectors must be the same.

`concurrency_id` can be `INF_ADOPTED_CONCURRENCY_NONE` even if the transformation requires a concurrency ID (see `inf_adopted_request_need_concurrency_id()`). In that case, it is assumed that it does not matter which operation to transform, and user IDs are used to determine a concurrency ID for the transformation.

`request` : | The request to transform.
`against` : | The request to transform against.
`concurrency_id` : | A concurrency ID for the transformation.
Returns : | A new InfAdoptedRequest, the result of the transformation.

### inf_adopted_request_mirror ()

    InfAdoptedRequest * inf_adopted_request_mirror          (InfAdoptedRequest *request,
                                                             guint by);

Mirrors `request` as described in "Reducing the Problems of Group Undo" by Matthias Ressel and Rul Gunzenhäuser (http://portal.acm.org/citation.cfm?doid=320297.320312).

Note that `by` is the total amount of requests between the original and mirrored request, and thus equivalent to 2j-1 in the paper's definition.

`request` must be of type `INF_ADOPTED_REQUEST_DO` and its operation must be reversible.

`request` : | A InfAdoptedRequest.
`by` : | The number of requests between the original and the mirrored operation.
Returns : | The mirrored request as a new InfAdoptedRequest.

### inf_adopted_request_fold ()

    InfAdoptedRequest * inf_adopted_request_fold            (InfAdoptedRequest *request,
                                                             guint into,
                                                             guint by);

Folds `request` as described in "Reducing the Problems of Group Undo" by Matthias Ressel and Rul Gunzenhäuser (http://portal.acm.org/citation.cfm?doid=320297.320312).

Note that `by` is the total amount of requests between the original and the fold request, and thus equivalent to 2j in the paper's definition.

`into` must not be the same user as the one that issued `request`.

`request` : | A InfAdoptedRequest.
`into` : | The direction into which to fold.
`by` : | The number of operations between the original and the fold request.
Returns : | The folded request as a new InfAdoptedRequest.

### inf_adopted_request_affects_buffer ()

    gboolean            inf_adopted_request_affects_buffer  (InfAdoptedRequest *request);

Returns whether this request, when applied, changes the content of the buffer. If this is a `INF_ADOPTED_REQUEST_UNDO` or `INF_ADOPTED_REQUEST_REDO` request, than it always affects the buffer, because only requests that affect the buffer can be undone or redone. If it is a `INF_ADOPTED_REQUEST_DO` request, than it returns whether its operation has the `INF_ADOPTED_OPERATION_AFFECTS_BUFFER` flag set.

`request` : | A InfAdoptedRequest.
Returns : | Whether `request` affects the session's buffer.

## Property Details

### The `"operation"` property

      "operation"                InfAdoptedOperation*  : Read / Write / Construct Only

The operation of the request.

### The `"type"` property

      "type"                     InfAdoptedRequestType  : Read / Write / Construct Only

The type of the operation.

Default value: INF_ADOPTED_REQUEST_DO

### The `"user-id"` property

      "user-id"                  guint                 : Read / Write / Construct Only

The ID of the user that made the request.

Default value: 0

### The `"vector"` property

      "vector"                   InfAdoptedStateVector*  : Read / Write / Construct Only

The vector time at which the request was made.

## See Also

InfAdoptedAlgorithm