![]() | ![]() | ![]() | Ximian Connector for Microsoft Exchange Programmer’s Reference Manual | ![]() |
---|
E2kContext — WebDAV connection to the Exchange server
struct E2kContext; E2kContext* e2k_context_new (constchar *uri);void e2k_context_set_auth (E2kContext *ctx, constchar *username, constchar *domain, constchar *authmech, constchar *password);gboolean e2k_context_fba (E2kContext *ctx,SoupMessage *failed_msg);time_t e2k_context_get_last_timestamp (E2kContext *ctx);gboolean (*E2kContextTestCallback) (E2kContext *ctx, constchar *test_name,gpointer user_data); E2kHTTPStatus e2k_context_get (E2kContext *ctx,E2kOperation *op, constchar *uri,char **content_type,char **body,int *len); E2kHTTPStatus e2k_context_get_owa (E2kContext *ctx,E2kOperation *op, constchar *uri,gboolean claim_ie,char **body,int *len); E2kHTTPStatus e2k_context_put (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar *content_type, constchar *body,int length,char **repl_uid); E2kHTTPStatus e2k_context_put_new (E2kContext *ctx,E2kOperation *op, constchar *folder_uri, constchar *object_name, E2kContextTestCallback test_callback,gpointer user_data, constchar *content_type, constchar *body,int length,char **location,char **repl_uid); E2kHTTPStatus e2k_context_post (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar *content_type, constchar *body,int length,char **location,char **repl_uid); E2kHTTPStatus e2k_context_proppatch (E2kContext *ctx,E2kOperation *op, constchar *uri,E2kProperties *props,gboolean create,char **repl_uid); E2kHTTPStatus e2k_context_proppatch_new (E2kContext *ctx,E2kOperation *op, constchar *folder_uri, constchar *object_name, E2kContextTestCallback test_callback,gpointer user_data,E2kProperties *props,char **location,char **repl_uid);E2kResultIter * e2k_context_bproppatch_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs,E2kProperties *props,gboolean create); E2kHTTPStatus e2k_context_propfind (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **props,int nprops, E2kResult **results,int *nresults);E2kResultIter * e2k_context_bpropfind_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs, constchar **props,int nprops);E2kResultIter * e2k_context_search_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **props,int nprops, E2kRestriction *rn, constchar *orderby,gboolean ascending); E2kHTTPStatus e2k_context_delete (E2kContext *ctx,E2kOperation *op, constchar *uri);E2kResultIter * e2k_context_bdelete_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs); E2kHTTPStatus e2k_context_mkcol (E2kContext *ctx,E2kOperation *op, constchar *uri,E2kProperties *props,char **permanent_url);E2kResultIter * e2k_context_transfer_start (E2kContext *ctx,E2kOperation *op, constchar *source_folder, constchar *dest_folder,GPtrArray *source_hrefs,gboolean delete_originals); E2kHTTPStatus e2k_context_transfer_dir (E2kContext *ctx,E2kOperation *op, constchar *source_href, constchar *dest_href,gboolean delete_original,char **permanent_url);void e2k_context_subscribe (E2kContext *ctx, constchar *uri, E2kContextChangeType type,int min_interval, E2kContextChangeCallback callback,gpointer user_data);void e2k_context_unsubscribe (E2kContext *ctx, constchar *uri); enum E2kContextChangeType;void (*E2kContextChangeCallback) (E2kContext *ctx, constchar *uri, E2kContextChangeType type,gpointer user_data);SoupMessage * e2k_soup_message_new (E2kContext *ctx, constchar *uri, constchar *method);SoupMessage * e2k_soup_message_new_full (E2kContext *ctx, constchar *uri, constchar *method, constchar *content_type,SoupOwnership owner, constchar *body,gulong length);void e2k_context_queue_message (E2kContext *ctx,SoupMessage *msg,SoupMessageCallbackFn callback,gpointer user_data); E2kHTTPStatus e2k_context_send_message (E2kContext *ctx,E2kOperation *op,SoupMessage *msg);
GObject +----E2kContext
E2kContext implements
"redirect"void user_function (E2kContext *e2kcontext,gint arg1,gchar *arg2,gchar *arg3,gpointer user_data);
E2kContext* e2k_context_new (constchar *uri);
Creates a new E2kContext based at uri
uri : | OWA uri to connect to |
Returns : | the new context |
void e2k_context_set_auth (E2kContext *ctx, constchar *username, constchar *domain, constchar *authmech, constchar *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 |
gboolean e2k_context_fba (E2kContext *ctx,SoupMessage *failed_msg);
Attempts to synchronously perform Exchange 2003 forms-based authentication.
ctx : | the context |
failed_msg : | a message that received a 440 status code |
Returns : | FALSE if authentication failed, TRUE if it succeeded, in which case failed_msg can be requeued. |
time_t e2k_context_get_last_timestamp (E2kContext *ctx);
Returns a time_t corresponding to the last "Date" header received from the server.
ctx : | the context |
Returns : | the timestamp |
gboolean (*E2kContextTestCallback) (E2kContext *ctx, constchar *test_name,gpointer user_data);
ctx : | |
test_name : | |
user_data : | |
Returns : |
E2kHTTPStatus e2k_context_get (E2kContext *ctx,E2kOperation *op, constchar *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 |
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 |
E2kHTTPStatus e2k_context_get_owa (E2kContext *ctx,E2kOperation *op, constchar *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 |
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 |
E2kHTTPStatus e2k_context_put (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar *content_type, constchar *body,int length,char **repl_uid);
Performs a PUT operation on ctx for uri.
ctx : | the context |
op : | pointer to an |
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 |
E2kHTTPStatus e2k_context_put_new (E2kContext *ctx,E2kOperation *op, constchar *folder_uri, constchar *object_name, E2kContextTestCallback test_callback,gpointer user_data, constchar *content_type, constchar *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 |
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 |
E2kHTTPStatus e2k_context_post (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar *content_type, constchar *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 |
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 |
E2kHTTPStatus e2k_context_proppatch (E2kContext *ctx,E2kOperation *op, constchar *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 |
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 |
E2kHTTPStatus e2k_context_proppatch_new (E2kContext *ctx,E2kOperation *op, constchar *folder_uri, constchar *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 |
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 |
E2kResultIter * e2k_context_bproppatch_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs,E2kProperties *props,gboolean create);
Begins a BPROPPATCH (bulk PROPPATCH) of hrefs based at uri.
ctx : | the context |
op : | pointer to an |
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 |
E2kHTTPStatus e2k_context_propfind (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **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 |
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 |
E2kResultIter * e2k_context_bpropfind_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs, constchar **props,int nprops);
Begins a BPROPFIND (bulk PROPFIND) operation on ctx for hrefs.
ctx : | the context |
op : | pointer to an |
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 |
E2kResultIter * e2k_context_search_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **props,int nprops, E2kRestriction *rn, constchar *orderby,gboolean ascending);
Begins a SEARCH on ctx at uri.
ctx : | the context |
op : | pointer to an |
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 |
E2kHTTPStatus e2k_context_delete (E2kContext *ctx,E2kOperation *op, constchar *uri);
Attempts to DELETE uri on ctx.
ctx : | the context |
op : | pointer to an |
uri : | URI to DELETE |
Returns : | the HTTP status |
E2kResultIter * e2k_context_bdelete_start (E2kContext *ctx,E2kOperation *op, constchar *uri, constchar **hrefs,int nhrefs);
Begins a BDELETE (bulk DELETE) operation on ctx for hrefs.
ctx : | the context |
op : | pointer to an |
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 |
E2kHTTPStatus e2k_context_mkcol (E2kContext *ctx,E2kOperation *op, constchar *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 |
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 |
E2kResultIter * e2k_context_transfer_start (E2kContext *ctx,E2kOperation *op, constchar *source_folder, constchar *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.
NB: may not work correctly if source_hrefs contains folders
ctx : | the context |
op : | pointer to an |
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 |
E2kHTTPStatus e2k_context_transfer_dir (E2kContext *ctx,E2kOperation *op, constchar *source_href, constchar *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 |
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 |
void e2k_context_subscribe (E2kContext *ctx, constchar *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. |
void e2k_context_unsubscribe (E2kContext *ctx, constchar *uri);
Unsubscribes to all notifications on ctx for uri.
ctx : | the context |
uri : | the URI to unsubscribe from |
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
void (*E2kContextChangeCallback) (E2kContext *ctx, constchar *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() |
SoupMessage * e2k_soup_message_new (E2kContext *ctx, constchar *uri, constchar *method);
Creates a new SoupMessage for ctx.
ctx : | the context |
uri : | the URI |
method : | the HTTP method |
Returns : | a new SoupMessage, set up for connector use |
SoupMessage * e2k_soup_message_new_full (E2kContext *ctx, constchar *uri, constchar *method, constchar *content_type,SoupOwnership owner, constchar *body,gulong length);
Creates a new SoupMessage with the given body.
ctx : | the context |
uri : | the URI |
method : | the HTTP method |
content_type : | MIME Content-Type of body |
owner : | ownership of body |
body : | request body |
length : | length of body |
Returns : | a new SoupMessage with a request body, set up for connector use |
void e2k_context_queue_message (E2kContext *ctx,SoupMessage *msg,SoupMessageCallbackFn callback,gpointer user_data);
Asynchronously queues msg in ctx's session.
ctx : | the context |
msg : | the message to queue |
callback : | callback to invoke when msg is done |
user_data : | data for callback |
E2kHTTPStatus e2k_context_send_message (E2kContext *ctx,E2kOperation *op,SoupMessage *msg);
Synchronously sends msg in ctx's session.
ctx : | the context |
op : | an |
msg : | the message to send |
Returns : | the HTTP status of the message |
void user_function (E2kContext *e2kcontext,gint arg1,gchar *arg2,gchar *arg3,gpointer user_data);
e2kcontext : | the object which received the signal. |
arg1 : | |
arg2 : | |
arg3 : | |
user_data : | user data set when the signal handler was connected. |
<< API Reference | e2k-properties >> |