E2kContext

## E2kContext E2kContext — WebDAV connection to the Exchange server |

## Synopsis

    struct      E2kContext;
    E2kContext* e2k_context_new                 (const char *uri);
    void        e2k_context_set_auth            (E2kContext *ctx,
                                                 const char *username,
                                                 const char *domain,
                                                 const char *authmech,
                                                 const char *password);

    E2kHTTPStatus e2k_context_get               (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 char **content_type,
                                                 char **body,
                                                 int *len);
    E2kHTTPStatus e2k_context_get_owa           (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 gboolean claim_ie,
                                                 char **body,
                                                 int *len);
    E2kHTTPStatus e2k_context_put               (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **repl_uid);
    E2kHTTPStatus e2k_context_post              (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **location,
                                                 char **repl_uid);
    E2kHTTPStatus e2k_context_proppatch         (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 E2kProperties *props,
                                                 gboolean create,
                                                 char **repl_uid);
    E2kResultIter* e2k_context_bproppatch_start (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs,
                                                 E2kProperties *props,
                                                 gboolean create);
    gboolean    (*E2kContextTestCallback)       (E2kContext *ctx,
                                                 const char *test_name,
                                                 gpointer user_data);
    E2kHTTPStatus e2k_context_put_new           (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *folder_uri,
                                                 const char *object_name,
                                                 E2kContextTestCallback test_callback,
                                                 gpointer user_data,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **location,
                                                 char **repl_uid);
    E2kHTTPStatus e2k_context_proppatch_new     (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *folder_uri,
                                                 const char *object_name,
                                                 E2kContextTestCallback test_callback,
                                                 gpointer user_data,
                                                 E2kProperties *props,
                                                 char **location,
                                                 char **repl_uid);
    E2kHTTPStatus e2k_context_propfind          (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **props,
                                                 int nprops,
                                                 E2kResult **results,
                                                 int *nresults);
    E2kResultIter* e2k_context_bpropfind_start  (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs,
                                                 const char **props,
                                                 int nprops);
    E2kResultIter* e2k_context_search_start     (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **props,
                                                 int nprops,
                                                 E2kRestriction *rn,
                                                 const char *orderby,
                                                 gboolean ascending);
    E2kHTTPStatus e2k_context_delete            (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri);
    E2kResultIter* e2k_context_bdelete_start    (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs);
    E2kHTTPStatus e2k_context_mkcol             (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 E2kProperties *props,
                                                 char **permanent_url);
    E2kResultIter* e2k_context_transfer_start   (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *source_folder,
                                                 const char *dest_folder,
                                                 GPtrArray *source_hrefs,
                                                 gboolean delete_originals);
    E2kHTTPStatus e2k_context_transfer_dir      (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *source_href,
                                                 const char *dest_href,
                                                 gboolean delete_original,
                                                 char **permanent_url);

    enum        E2kContextChangeType;
    void        (*E2kContextChangeCallback)     (E2kContext *ctx,
                                                 const char *uri,
                                                 E2kContextChangeType type,
                                                 gpointer user_data);
    void        e2k_context_subscribe           (E2kContext *ctx,
                                                 const char *uri,
                                                 E2kContextChangeType type,
                                                 int min_interval,
                                                 E2kContextChangeCallback callback,
                                                 gpointer user_data);
    void        e2k_context_unsubscribe         (E2kContext *ctx,
                                                 const char *uri);

## Object Hierarchy

      GObject
       +----E2kContext

## Implemented Interfaces

E2kContext implements SoupMessageFilter.

## Signal Prototypes

    "redirect"  void        user_function      (E2kContext *e2kcontext,
                                                gint arg1,
                                                gchar *arg2,
                                                gchar *arg3,
                                                gpointer user_data);

## Description

## Details

### struct E2kContext

    struct E2kContext;

E2kContext manages the pool of WebDAV connections to the Exchange server.

### e2k_context_new ()

    E2kContext* e2k_context_new                 (const char *uri);

Creates a new E2kContext based at `uri`

`uri` : | OWA uri to connect to
Returns : | the new context

### e2k_context_set_auth ()

    void        e2k_context_set_auth            (E2kContext *ctx,
                                                 const char *username,
                                                 const char *domain,
                                                 const char *authmech,
                                                 const char *password);

Sets the authentication information on `ctx`. This will have the side effect of cancelling any pending requests on `ctx`.

`ctx` : | the context
`username` : | the Windows username (not including domain) of the user
`domain` : | the NT domain, or `NULL` to use the default (if using NTLM)
`authmech` : | the HTTP Authorization type to use; either "Basic" or "NTLM"
`password` : | the user's password

### e2k_context_get ()

    E2kHTTPStatus e2k_context_get               (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 char **content_type,
                                                 char **body,
                                                 int *len);

Performs a GET on `ctx` for `uri`. If successful (2xx status code), the Content-Type, body and length will be returned. The body is not terminated by a '\0'. If the GET is not successful, `content_type`, `body` and `len` will be untouched (even if the error response included a body).

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | URI of the object to GET
`content_type` : | if not `NULL`, will contain the Content-Type of the response on return.
`body` : | if not `NULL`, will contain the response body on return
`len` : | if not `NULL`, will contain the response body length on return
Returns : | the HTTP status

### e2k_context_get_owa ()

    E2kHTTPStatus e2k_context_get_owa           (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 gboolean claim_ie,
                                                 char **body,
                                                 int *len);

As with `e2k_context_get()`, but used when you need the HTML or XML data that would be returned to OWA rather than the raw object data.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | URI of the object to GET
`claim_ie` : | whether or not to claim to be IE
`body` : | if not `NULL`, will contain the response body on return
`len` : | if not `NULL`, will contain the response body length on return
Returns : | the HTTP status

### e2k_context_put ()

    E2kHTTPStatus e2k_context_put               (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **repl_uid);

Performs a PUT operation on `ctx` for `uri`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the URI to PUT to
`content_type` : | MIME Content-Type of the data
`body` : | data to PUT
`length` : | length of `body`
`repl_uid` : | if not `NULL`, will contain the Repl-UID of the PUT object on return
Returns : | the HTTP status

### e2k_context_post ()

    E2kHTTPStatus e2k_context_post              (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **location,
                                                 char **repl_uid);

Performs a POST operation on `ctx` for `uri`.

Note that POSTed objects will be irrevocably(?) marked as "unsent", If you open a POSTed message in Outlook, it will open in the composer rather than in the message viewer.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the URI to POST to
`content_type` : | MIME Content-Type of the data
`body` : | data to PUT
`length` : | length of `body`
`location` : | if not `NULL`, will contain the Location of the POSTed object on return
`repl_uid` : | if not `NULL`, will contain the Repl-UID of the POSTed object on return
Returns : | the HTTP status

### e2k_context_proppatch ()

    E2kHTTPStatus e2k_context_proppatch         (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 E2kProperties *props,
                                                 gboolean create,
                                                 char **repl_uid);

Performs a PROPPATCH operation on `ctx` for `uri`.

If `create` is `FALSE` and `uri` does not already exist, the response code will be `E2K_HTTP_PRECONDITION_FAILED`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the URI to PROPPATCH
`props` : | the properties to set/remove
`create` : | whether or not to create `uri` if it does not exist
`repl_uid` : | if not `NULL`, will contain the Repl-UID of the PROPPATCHed object on return
Returns : | the HTTP status

### e2k_context_bproppatch_start ()

    E2kResultIter* e2k_context_bproppatch_start (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs,
                                                 E2kProperties *props,
                                                 gboolean create);

Begins a BPROPPATCH (bulk PROPPATCH) of `hrefs` based at `uri`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the base URI
`hrefs` : | array of URIs, possibly relative to `uri`
`nhrefs` : | length of `hrefs`
`props` : | the properties to set/remove
`create` : | whether or not to create `uri` if it does not exist
Returns : | an iterator for getting the results of the BPROPPATCH

### E2kContextTestCallback ()

    gboolean    (*E2kContextTestCallback)       (E2kContext *ctx,
                                                 const char *test_name,
                                                 gpointer user_data);

Used by `e2k_context_put_new()` and `e2k_context_proppatch_new()`, qv.

`ctx` : | the context
`test_name` : | the object name to test the existence of
`user_data` : | user data that was passed along with the callback
Returns : | `TRUE` if `test_name` is available, `FALSE` if it is in use.

### e2k_context_put_new ()

    E2kHTTPStatus e2k_context_put_new           (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *folder_uri,
                                                 const char *object_name,
                                                 E2kContextTestCallback test_callback,
                                                 gpointer user_data,
                                                 const char *content_type,
                                                 const char *body,
                                                 int length,
                                                 char **location,
                                                 char **repl_uid);

PUTs data into `folder_uri` on `ctx` with a new name based on `object_name`. If `test_callback` is non-`NULL`, it will be called with each URI that is considered for the object so that the caller can check its summary data to see if that URI is in use (potentially saving one or more round-trips to the server).

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`folder_uri` : | the URI of the folder to PUT into
`object_name` : | base name of the new object (not URI-encoded)
`test_callback` : | callback to use to test possible object URIs
`user_data` : | data for `test_callback`
`content_type` : | MIME Content-Type of the data
`body` : | data to PUT
`length` : | length of `body`
`location` : | if not `NULL`, will contain the Location of the PUT object on return
`repl_uid` : | if not `NULL`, will contain the Repl-UID of the PUT object on return
Returns : | the HTTP status

### e2k_context_proppatch_new ()

    E2kHTTPStatus e2k_context_proppatch_new     (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *folder_uri,
                                                 const char *object_name,
                                                 E2kContextTestCallback test_callback,
                                                 gpointer user_data,
                                                 E2kProperties *props,
                                                 char **location,
                                                 char **repl_uid);

PROPPATCHes data into `folder_uri` on `ctx` with a new name based on `object_name`. If `test_callback` is non-`NULL`, it will be called with each URI that is considered for the object so that the caller can check its summary data to see if that URI is in use (potentially saving one or more round-trips to the server).

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`folder_uri` : | the URI of the folder to PROPPATCH a new object in
`object_name` : | base name of the new object (not URI-encoded)
`test_callback` : | callback to use to test possible object URIs
`user_data` : | data for `test_callback`
`props` : | the properties to set/remove
`location` : | if not `NULL`, will contain the Location of the PROPPATCHed object on return
`repl_uid` : | if not `NULL`, will contain the Repl-UID of the PROPPATCHed object on return
Returns : | the HTTP status

### e2k_context_propfind ()

    E2kHTTPStatus e2k_context_propfind          (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **props,
                                                 int nprops,
                                                 E2kResult **results,
                                                 int *nresults);

Performs a PROPFIND operation on `ctx` for `uri`. If successful, the results are returned as an array of E2kResult (which you must free with `e2k_results_free()`), but the array will always have either 0 or 1 members.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the URI to PROPFIND on
`props` : | array of properties to find
`nprops` : | length of `props`
`results` : | on return, the results
`nresults` : | length of `results`
Returns : | the HTTP status

### e2k_context_bpropfind_start ()

    E2kResultIter* e2k_context_bpropfind_start  (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs,
                                                 const char **props,
                                                 int nprops);

Begins a BPROPFIND (bulk PROPFIND) operation on `ctx` for `hrefs`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the base URI
`hrefs` : | array of URIs, possibly relative to `uri`
`nhrefs` : | length of `hrefs`
`props` : | array of properties to find
`nprops` : | length of `props`
Returns : | an iterator for getting the results

### e2k_context_search_start ()

    E2kResultIter* e2k_context_search_start     (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **props,
                                                 int nprops,
                                                 E2kRestriction *rn,
                                                 const char *orderby,
                                                 gboolean ascending);

Begins a SEARCH on `ctx` at `uri`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the folder to search
`props` : | the properties to search for
`nprops` : | size of `props` array
`rn` : | the search restriction
`orderby` : | if non-`NULL`, the field to sort the search results by
`ascending` : | `TRUE` for an ascending search, `FALSE` for descending.
Returns : | an iterator for returning the search results

### e2k_context_delete ()

    E2kHTTPStatus e2k_context_delete            (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri);

Attempts to DELETE `uri` on `ctx`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | URI to DELETE
Returns : | the HTTP status

### e2k_context_bdelete_start ()

    E2kResultIter* e2k_context_bdelete_start    (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 const char **hrefs,
                                                 int nhrefs);

Begins a BDELETE (bulk DELETE) operation on `ctx` for `hrefs`.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | the base URI
`hrefs` : | array of URIs, possibly relative to `uri`, to delete
`nhrefs` : | length of `hrefs`
Returns : | an iterator for returning the results

### e2k_context_mkcol ()

    E2kHTTPStatus e2k_context_mkcol             (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *uri,
                                                 E2kProperties *props,
                                                 char **permanent_url);

Performs a MKCOL operation on `ctx` to create `uri`, with optional additional properties.

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`uri` : | URI of the new folder
`props` : | properties to set on the new folder, or `NULL`
`permanent_url` : | if not `NULL`, will contain the permanent URL of the new folder on return
Returns : | the HTTP status

### e2k_context_transfer_start ()

    E2kResultIter* e2k_context_transfer_start   (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *source_folder,
                                                 const char *dest_folder,
                                                 GPtrArray *source_hrefs,
                                                 gboolean delete_originals);

Starts a BMOVE or BCOPY (depending on `delete_originals`) operation on `ctx` for `source_folder`. The objects in `source_folder` described by `source_hrefs` will be moved or copied to `dest_folder`. `e2k_result_iter_next()` can be used to check the success or failure of each move/copy. (The E2K_PR_DAV_LOCATION property for each result will show the new location of the object.)

NB: may not work correctly if `source_hrefs` contains folders

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`source_folder` : | URI of the source folder
`dest_folder` : | URI of the destination folder
`source_hrefs` : | an array of hrefs to move, relative to `source_folder`
`delete_originals` : | whether or not to delete the original objects
Returns : | the iterator for the results

### e2k_context_transfer_dir ()

    E2kHTTPStatus e2k_context_transfer_dir      (E2kContext *ctx,
                                                 E2kOperation *op,
                                                 const char *source_href,
                                                 const char *dest_href,
                                                 gboolean delete_original,
                                                 char **permanent_url);

Performs a MOVE or COPY (depending on `delete_original`) operation on `ctx` for `source_href`. The folder itself will be moved, renamed, or copied to `dest_href` (which is the name of the new folder itself, not its parent).

`ctx` : | the context
`op` : | pointer to an E2kOperation to use for cancellation
`source_href` : | URI of the source folder
`dest_href` : | URI of the destination folder
`delete_original` : | whether or not to delete the original folder
`permanent_url` : | if not `NULL`, will contain the permanent URL of the new folder on return
Returns : | the HTTP status

### enum E2kContextChangeType

    typedef enum {
    	E2K_CONTEXT_OBJECT_CHANGED,
    	E2K_CONTEXT_OBJECT_ADDED,
    	E2K_CONTEXT_OBJECT_REMOVED,
    	E2K_CONTEXT_OBJECT_MOVED
    } E2kContextChangeType;

The kinds of change notification you can subscribe to on a folder.

`E2K_CONTEXT_OBJECT_CHANGED` | Notification of any changes to the folder.
`E2K_CONTEXT_OBJECT_ADDED` | Notification when objects are added to the folder.
`E2K_CONTEXT_OBJECT_REMOVED` | Notification when objects are DELETEd from the folder.
`E2K_CONTEXT_OBJECT_MOVED` | Notification when objects are moved into or out of the folder.

### E2kContextChangeCallback ()

    void        (*E2kContextChangeCallback)     (E2kContext *ctx,
                                                 const char *uri,
                                                 E2kContextChangeType type,
                                                 gpointer user_data);

The callback that is invoked when a subscription is triggered.

`ctx` : | the context
`uri` : | the URI for which a notification was received
`type` : | the type of notification (so you can use the same callback for multiple subscription types)
`user_data` : | the data that was passed to `e2k_context_subscribe()`

### e2k_context_subscribe ()

    void        e2k_context_subscribe           (E2kContext *ctx,
                                                 const char *uri,
                                                 E2kContextChangeType type,
                                                 int min_interval,
                                                 E2kContextChangeCallback callback,
                                                 gpointer user_data);

This subscribes to change notifications of the given `type` on `uri`. `callback` will (eventually) be invoked any time the folder changes in the given way: whenever an object is added to it for `E2K_CONTEXT_OBJECT_ADDED`, whenever an object is deleted (but not moved) from it (or the folder itself is deleted) for `E2K_CONTEXT_OBJECT_REMOVED`, whenever an object is moved in or out of the folder for `E2K_CONTEXT_OBJECT_MOVED`, and whenever any of the above happens, or the folder or one of its items is modified, for `E2K_CONTEXT_OBJECT_CHANGED`. (This means that if you subscribe to both CHANGED and some other notification on the same folder that multiple callbacks may be invoked every time an object is added/removed/moved/etc.)

Notifications can be used *only* to discover changes made by other clients! The code cannot assume that it will receive a notification for every change that it makes to the server, for two reasons:

First, if multiple notifications occur within `min_interval` seconds of each other, the later ones will be suppressed, to avoid excessive traffic between the client and the server as the client tries to sync. Second, if there is a firewall between the client and the server, it is possible that all notifications will be lost.

`ctx` : | the context
`uri` : | the folder URI to subscribe to notifications on
`type` : | the type of notification to subscribe to
`min_interval` : | the minimum interval (in seconds) between notifications.
`callback` : | the callback to call when a notification has been received
`user_data` : | data to pass to `callback`.

### e2k_context_unsubscribe ()

    void        e2k_context_unsubscribe         (E2kContext *ctx,
                                                 const char *uri);

Unsubscribes to all notifications on `ctx` for `uri`.

`ctx` : | the context
`uri` : | the URI to unsubscribe from

## Signals

### The "redirect" signal

    void        user_function                  (E2kContext *e2kcontext,
                                                gint arg1,
                                                gchar *arg2,
                                                gchar *arg3,
                                                gpointer user_data);

Indicates that `e2kcontext` has processed a redirection response. The application can use this to update its records so that the correct URI can be used automatically in the future.

`e2kcontext` : | the object which received the signal.
`arg1` : | the HTTP status code
`arg2` : | the originally-requested URI
`arg3` : | the URI `old_uri` was redirected to
`user_data` : | user data set when the signal handler was connected.

## See Also

E2kAutoconfig, E2kOperation, E2kResult, E2kProperties

The private E2kContext API.