e2k-utils

## e2k-utils e2k-utils — Random utility functions |

## Synopsis

    time_t              e2k_parse_timestamp                 (const gchar *timestamp);
    gchar *             e2k_make_timestamp                  (time_t when);
    gchar *             e2k_make_timestamp_rfc822           (time_t when);

    time_t              e2k_systime_to_time_t               (guint32 systime);
    guint32             e2k_systime_from_time_t             (time_t tt);
    time_t              e2k_filetime_to_time_t              (guint64 filetime);
    guint64             e2k_filetime_from_time_t            (time_t tt);

    gchar *             e2k_lf_to_crlf                      (const gchar *in);
    gchar *             e2k_crlf_to_lf                      (const gchar *in);

    gchar *             e2k_strdup_with_trailing_slash      (const gchar *path);

    const gchar *       e2k_entryid_to_dn                   (GByteArray *entryid);

    gint                e2k_ascii_strcase_equal             (gconstpointer v,
                                                             gconstpointer v2);
    guint               e2k_ascii_strcase_hash              (gconstpointer v);

    gboolean            e2k_restriction_folders_only        (E2kRestriction *rn);

    GByteArray *        e2k_entryid_generate_oneoff         (const gchar *display_name,
                                                             const gchar *email,
                                                             gboolean unicode);
    GByteArray *        e2k_entryid_generate_local          (const gchar *exchange_dn);
    GByteArray *        e2k_entryid_generate_contact        (GByteArray *contact_entryid,
                                                             gint nth_address);
    GByteArray *        e2k_search_key_generate             (const gchar *addrtype,
                                                             const gchar *address);

    gchar *             e2k_entryid_to_permanenturl         (GByteArray *entryid,
                                                             const gchar *base_uri);
    GByteArray *        e2k_permanenturl_to_entryid         (const gchar *permanenturl);

## Description

## Details

### e2k_parse_timestamp ()

    time_t              e2k_parse_timestamp                 (const gchar *timestamp);

Converts `timestamp` to a `time_t` value. `timestamp` must be in one of the two ISO8601 variants used by Exchange.

Note that the timestamps used (in most contexts) by Exchange have millisecond resolution, so converting them to `time_t` loses resolution. Since ISO8601 timestamps can be compared using `strcmp()`, it is often best to keep them as strings.

`timestamp` : | an ISO8601 timestamp returned by the Exchange server
Returns : | the `time_t` corresponding to `timestamp`, or -1 on error.

### e2k_make_timestamp ()

    gchar *             e2k_make_timestamp                  (time_t when);

Creates an ISO8601 timestamp (in an format acceptable to Exchange) corresponding to `when`.

`when` : | the `time_t` to convert to an ISO8601 timestamp
Returns : | the timestamp, which the caller must free.

### e2k_make_timestamp_rfc822 ()

    gchar *             e2k_make_timestamp_rfc822           (time_t when);

Creates an RFC822 Date header value corresponding to `when`, in the locale timezone.

`when` : | the `time_t` to convert to an RFC822 timestamp
Returns : | the timestamp, which the caller must free.

### e2k_systime_to_time_t ()

    time_t              e2k_systime_to_time_t               (guint32 systime);

Converts the MAPI PT_SYSTIME value `systime` to a corresponding `time_t` value (assuming it is within the valid range of a `time_t`).

`systime` : | a MAPI PT_SYSTIME value (minutes since Windows epoch)
Returns : | a `time_t` corresponding to `systime`.

### e2k_systime_from_time_t ()

    guint32             e2k_systime_from_time_t             (time_t tt);

Converts the `time_t` value `tt` to a corresponding MAPI PT_SYSTIME value, losing some precision if `tt` does not fall on a minute boundary.

`tt` : | a `time_t` value
Returns : | the Windows systime value corresponding to `tt`

### e2k_filetime_to_time_t ()

    time_t              e2k_filetime_to_time_t              (guint64 filetime);

Converts the Windows FILETIME value `filetime` to a corresponding `time_t` value (assuming it is within the valid range of a `time_t`), truncating to a second boundary.

`filetime` : | a Windows FILETIME value (100ns intervals since Windows epoch)
Returns : | a `time_t` corresponding to `filetime`.

### e2k_filetime_from_time_t ()

    guint64             e2k_filetime_from_time_t            (time_t tt);

Converts the `time_t` value `tt` to a corresponding Windows FILETIME value.

`tt` : | a `time_t` value
Returns : | the Windows FILETIME value corresponding to `tt`

### e2k_lf_to_crlf ()

    gchar *             e2k_lf_to_crlf                      (const gchar *in);

Creates a copy of `in` with all LFs converted to CRLFs.

`in` : | input text in UNIX ("\n") format
Returns : | the converted text, which the caller must free.

### e2k_crlf_to_lf ()

    gchar *             e2k_crlf_to_lf                      (const gchar *in);

Creates a copy of `in` with all CRLFs converted to LFs. (Actually, it just strips CRs, so any raw CRs will be removed.)

`in` : | input text in network ("\r\n") format
Returns : | the converted text, which the caller must free.

### e2k_strdup_with_trailing_slash ()

    gchar *             e2k_strdup_with_trailing_slash      (const gchar *path);

Copies `path`, appending a "/" to it if and only if it did not already end in "/".

`path` : | a URI or path
Returns : | the path, which the caller must free

### e2k_entryid_to_dn ()

    const gchar *       e2k_entryid_to_dn                   (GByteArray *entryid);

Finds an Exchange 5.5 DN inside a binary entryid property (such as PR_STORE_ENTRYID or an element of PR_DELEGATES_ENTRYIDS).

`entryid` : | an Exchange entryid
Returns : | the entryid, which is a pointer into `entryid`'s data.

### e2k_ascii_strcase_equal ()

    gint                e2k_ascii_strcase_equal             (gconstpointer v,
                                                             gconstpointer v2);

ASCII-case-insensitive comparison function for use with GHashTable.

`v` : | a string
`v2` : | another string
Returns : | `TRUE` if `v` and `v2` are ASCII-case-insensitively equal, `FALSE` if not.

### e2k_ascii_strcase_hash ()

    guint               e2k_ascii_strcase_hash              (gconstpointer v);

ASCII-case-insensitive hash function for use with GHashTable.

`v` : | a string
Returns : | An ASCII-case-insensitive hashing of `v`.

### e2k_restriction_folders_only ()

    gboolean            e2k_restriction_folders_only        (E2kRestriction *rn);

Examines `rn`, and determines if it can only return folders

`rn` : | a restriction
Returns : | `TRUE` if `rn` will cause only folders to be returned

### e2k_entryid_generate_oneoff ()

    GByteArray *        e2k_entryid_generate_oneoff         (const gchar *display_name,
                                                             const gchar *email,
                                                             gboolean unicode);

Constructs a "one-off" ENTRYID value that can be used as a MAPI recipient (eg, for a message forwarding server-side rule), corresponding to `display_name` and `email`.

`display_name` : | the display name of the user
`email` : | the email address
`unicode` : | `TRUE` to generate a Unicode ENTRYID (in which case `display_name` should be UTF-8), `FALSE` for an ASCII ENTRYID.
Returns : | the recipient ENTRYID

### e2k_entryid_generate_local ()

    GByteArray *        e2k_entryid_generate_local          (const gchar *exchange_dn);

Constructs an ENTRYID value that can be used as a MAPI recipient (eg, for a message forwarding server-side rule), corresponding to the local user identified by `exchange_dn`.

`exchange_dn` : | the Exchange 5.5-style DN of the local user
Returns : | the recipient ENTRYID

### e2k_entryid_generate_contact ()

    GByteArray *        e2k_entryid_generate_contact        (GByteArray *contact_entryid,
                                                             gint nth_address);

Constructs an ENTRYID value that can be used as a MAPI recipient (eg, for a message forwarding server-side rule), corresponding to the Contacts folder entry identified by `contact_entryid`.

`contact_entryid` : | the PR_ENTRYID of an item in the user's Contacts folder.
`nth_address` : | which of the contact's email addresses to use.
Returns : | the recipient ENTRYID

### e2k_search_key_generate ()

    GByteArray *        e2k_search_key_generate             (const gchar *addrtype,
                                                             const gchar *address);

Constructs a PR_SEARCH_KEY value for `address`

`addrtype` : | the type of `address` (usually "SMTP" or "EX")
`address` : | the address data
Returns : | the search key

### e2k_entryid_to_permanenturl ()

    gchar *             e2k_entryid_to_permanenturl         (GByteArray *entryid,
                                                             const gchar *base_uri);

Creates a permanenturl based on `entryid` and `base_uri`.

`entryid` : | an ENTRYID (specifically, a PR_SOURCE_KEY)
`base_uri` : | base URI of the store containing `entryid`
Returns : | the permanenturl, which the caller must free.

### e2k_permanenturl_to_entryid ()

    GByteArray *        e2k_permanenturl_to_entryid         (const gchar *permanenturl);

Creates an ENTRYID (specifically, a PR_SOURCE_KEY) based on `permanenturl`

`permanenturl` : | an Exchange permanenturl
Returns : | the entryid