E2kContext

E2kContext — WebDAV connection to the Exchange server

Synopsis

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

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

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

Object Hierarchy

  GObject
   +----E2kContext

Signals

  "redirect"                                       : Run Last

Description

Details

struct E2kContext

struct E2kContext;


e2k_context_new ()

E2kContext *        e2k_context_new                     (const gchar *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 gchar *username,
                                                         const gchar *domain,
                                                         const gchar *authmech,
                                                         const gchar *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 gchar *uri,
                                                         gchar **content_type,
                                                         SoupBuffer **response);

Performs a GET on ctx for uri. If successful (2xx status code), the Content-Type, and response body will be returned. The body is not terminated by a '\0'. If the GET is not successful, content_type and response 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.

response :

if not NULL, will contain the response on return

Returns :

the HTTP status

e2k_context_get_owa ()

E2kHTTPStatus       e2k_context_get_owa                 (E2kContext *ctx,
                                                         E2kOperation *op,
                                                         const gchar *uri,
                                                         gboolean claim_ie,
                                                         SoupBuffer **response);

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

response :

if not NULL, will contain the response on return

Returns :

the HTTP status

e2k_context_put ()

E2kHTTPStatus       e2k_context_put                     (E2kContext *ctx,
                                                         E2kOperation *op,
                                                         const gchar *uri,
                                                         const gchar *content_type,
                                                         const gchar *body,
                                                         gint length,
                                                         gchar **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 gchar *uri,
                                                         const gchar *content_type,
                                                         const gchar *body,
                                                         gint length,
                                                         gchar **location,
                                                         gchar **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 gchar *uri,
                                                         E2kProperties *props,
                                                         gboolean create,
                                                         gchar **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 gchar *uri,
                                                         const gchar **hrefs,
                                                         gint 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 gchar *test_name,
                                                         gpointer user_data);

ctx :

test_name :

user_data :

Returns :


e2k_context_put_new ()

E2kHTTPStatus       e2k_context_put_new                 (E2kContext *ctx,
                                                         E2kOperation *op,
                                                         const gchar *folder_uri,
                                                         const gchar *object_name,
                                                         E2kContextTestCallback test_callback,
                                                         gpointer user_data,
                                                         const gchar *content_type,
                                                         const gchar *body,
                                                         gint length,
                                                         gchar **location,
                                                         gchar **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 gchar *folder_uri,
                                                         const gchar *object_name,
                                                         E2kContextTestCallback test_callback,
                                                         gpointer user_data,
                                                         E2kProperties *props,
                                                         gchar **location,
                                                         gchar **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 gchar *uri,
                                                         const gchar **props,
                                                         gint nprops,
                                                         E2kResult **results,
                                                         gint *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 gchar *uri,
                                                         const gchar **hrefs,
                                                         gint nhrefs,
                                                         const gchar **props,
                                                         gint 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 gchar *uri,
                                                         const gchar **props,
                                                         gint nprops,
                                                         E2kRestriction *rn,
                                                         const gchar *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 gchar *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 gchar *uri,
                                                         const gchar **hrefs,
                                                         gint 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 gchar *uri,
                                                         E2kProperties *props,
                                                         gchar **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 gchar *source_folder,
                                                         const gchar *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 gchar *source_href,
                                                         const gchar *dest_href,
                                                         gboolean delete_original,
                                                         gchar **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;


E2kContextChangeCallback ()

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

ctx :

uri :

type :

user_data :


e2k_context_subscribe ()

void                e2k_context_subscribe               (E2kContext *ctx,
                                                         const gchar *uri,
                                                         E2kContextChangeType type,
                                                         gint 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 gchar *uri);

Unsubscribes to all notifications on ctx for uri.

ctx :

the context

uri :

the URI to unsubscribe from

Signal Details

The "redirect" signal

void                user_function                      (E2kContext *e2kcontext,
                                                        gint        arg1,
                                                        gchar      *arg2,
                                                        gchar      *arg3,
                                                        gpointer    user_data)       : Run Last

e2kcontext :

the object which received the signal.

arg1 :

arg2 :

arg3 :

user_data :

user data set when the signal handler was connected.

See Also

E2kAutoconfig, E2kOperation, E2kResult, E2kProperties

The private E2kContext API.