InfAdoptedRequest: libinfinity-0.7 Reference Manual

## InfAdoptedRequest InfAdoptedRequest — Request processed by InfAdoptedAlgorithm. |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfAdoptedRequest * | inf_adopted_request_new_do ()
InfAdoptedRequest * | inf_adopted_request_new_undo ()
InfAdoptedRequest * | inf_adopted_request_new_redo ()
InfAdoptedRequest * | inf_adopted_request_copy ()
InfAdoptedRequestType | inf_adopted_request_get_request_type ()
InfAdoptedStateVector * | inf_adopted_request_get_vector ()
guint | inf_adopted_request_get_user_id ()
InfAdoptedOperation * | inf_adopted_request_get_operation ()
guint | inf_adopted_request_get_index ()
gint64 | inf_adopted_request_get_receive_time ()
gint64 | inf_adopted_request_get_execute_time ()
void | inf_adopted_request_set_execute_time ()
gboolean | inf_adopted_request_need_concurrency_id ()
InfAdoptedRequest * | inf_adopted_request_transform ()
InfAdoptedRequest * | inf_adopted_request_mirror ()
InfAdoptedRequest * | inf_adopted_request_fold ()
gboolean | inf_adopted_request_affects_buffer ()

## Properties

gint64 | executed | Read / Write
InfAdoptedOperation * | operation | Read / Write / Construct Only
gint64 | received | Read / Write / Construct Only
InfAdoptedRequestType | type | Read / Write / Construct Only
guint | user-id | Read / Write / Construct Only
InfAdoptedStateVector * | vector | Read / Write / Construct Only

## Types and Values

enum | InfAdoptedRequestType
struct | InfAdoptedRequest
struct | InfAdoptedRequestClass

## Object Hierarchy

        GEnum
        ╰── InfAdoptedRequestType
        GObject
        ╰── InfAdoptedRequest

## Includes

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

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

## Functions

### inf_adopted_request_new_do ()

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

Creates a new InfAdoptedRequest with type `INF_ADOPTED_REQUEST_DO`.

[constructor]

#### Parameters

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. |
received | Time the request was received, in microseconds since the epoch. |

#### Returns

A new DO request.

[transfer full]

### inf_adopted_request_new_undo ()

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

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.

[constructor]

#### Parameters

vector | The vector time at which the request was made. |
user_id | The ID of the user that made the request. |
received | Time the request was received, in microseconds since the epoch. |

#### Returns

A new UNDO request.

[transfer full]

### inf_adopted_request_new_redo ()

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

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.

[constructor]

#### Parameters

vector | The vector time at which the request was made. |
user_id | The ID of the user that made the request. |
received | Time the request was received, in microseconds since the epoch. |

#### Returns

A new REDO request.

[transfer full]

### inf_adopted_request_copy ()

    InfAdoptedRequest *
    inf_adopted_request_copy (InfAdoptedRequest *request);

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

#### Parameters

request | The InfAdoptedRequest to copy. |

#### Returns

A new InfAdoptedRequest.

[transfer full]

### inf_adopted_request_get_request_type ()

    InfAdoptedRequestType
    inf_adopted_request_get_request_type (InfAdoptedRequest *request);

Returns the request type of `request` .

#### Parameters

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.

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

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

[transfer none]

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

#### Parameters

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

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

The request's operation.

[transfer none]

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

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

The vector time component of the request's own user.

### inf_adopted_request_get_receive_time ()

    gint64
    inf_adopted_request_get_receive_time (InfAdoptedRequest *request);

Returns the time when the request was received, or, if it's a local request, generated. The time is given in microseconds since January 1, 1970.

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

Time when the request was received.

### inf_adopted_request_get_execute_time ()

    gint64
    inf_adopted_request_get_execute_time (InfAdoptedRequest *request);

Returns the time when the request was executed by an InfAdoptedAlgorithm, see `inf_adopted_algorithm_execute_request()`. The time is given in microseconds since January 1, 1970. If the request was not yet executed, the function returns 0.

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

The time when the function was executed, or 0.

### inf_adopted_request_set_execute_time ()

    void
    inf_adopted_request_set_execute_time (InfAdoptedRequest *request,
                                          gint64 time);

Sets the time when `request` was executed. Usually this is called by InfAdoptedAlgorithm when it executes a request, i.e. translates it to the current state of the document.

#### Parameters

request | A InfAdoptedRequest. |
time | A time in microseconds since January 1, 1970. |

### 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. If this function returns `TRUE`, you must provide the `request_lcs` and `against_lcs` parameters when calling `inf_adopted_request_transform()`.

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

#### Parameters

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_transform ()

    InfAdoptedRequest *
    inf_adopted_request_transform (InfAdoptedRequest *request,
                                   InfAdoptedRequest *against,
                                   InfAdoptedRequest *request_lcs,
                                   InfAdoptedRequest *against_lcs);

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.

If the function `inf_adopted_request_need_concurrency_id()` returns `TRUE`, `request_lcs` and `against_lcs` must not be `NULL`.

#### Parameters

request | The request to transform. |
against | The request to transform against. |
request_lcs | The request to transform in a previous state, or `NULL`. |
against_lcs | The request to transform against in a previous state, or `NULL`. |

#### Returns

A new InfAdoptedRequest, the result of the transformation.

[transfer full]

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

#### Parameters

request | A InfAdoptedRequest. |
by | The number of requests between the original and the mirrored operation. |

#### Returns

The mirrored request as a new InfAdoptedRequest.

[transfer full]

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

#### Parameters

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.

[transfer full]

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

#### Parameters

request | A InfAdoptedRequest. |

#### Returns

Whether `request` affects the session's buffer.

## Types and Values

### enum InfAdoptedRequestType

Possible types for an InfAdoptedRequest.

#### Members

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

### struct InfAdoptedRequest

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

## Property Details

### The `“executed”` property

      “executed”                 gint64

Time the request was executed, in microseconds.

Owner: InfAdoptedRequest

Flags: Read / Write

Default value: 0

### The `“operation”` property

      “operation”                InfAdoptedOperation *

The operation of the request.

Owner: InfAdoptedRequest

Flags: Read / Write / Construct Only

### The `“received”` property

      “received”                 gint64

Time the request was received, in microseconds.

Owner: InfAdoptedRequest

Flags: Read / Write / Construct Only

Default value: 0

### The `“type”` property

      “type”                     InfAdoptedRequestType

The type of the operation.

Owner: InfAdoptedRequest

Flags: Read / Write / Construct Only

Default value: INF_ADOPTED_REQUEST_DO

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

      “user-id”                  guint

The ID of the user that made the request.

Owner: InfAdoptedRequest

Flags: Read / Write / Construct Only

Default value: 0

### The `“vector”` property

      “vector”                   InfAdoptedStateVector *

The vector time at which the request was made.

Owner: InfAdoptedRequest

Flags: Read / Write / Construct Only

## See Also

InfAdoptedAlgorithm