E2kGlobalCatalog

## E2kGlobalCatalog E2kGlobalCatalog — Connection to the local Active Directory Global Catalog replica server |

## Synopsis

    struct      E2kGlobalCatalog;
    E2kGlobalCatalog* e2k_global_catalog_new    (const char *server,
                                                 int response_limit,
                                                 const char *user,
                                                 const char *domain,
                                                 const char *password);
    LDAP*       e2k_global_catalog_get_ldap     (E2kGlobalCatalog *gc,
                                                 E2kOperation *op);

    enum        E2kGlobalCatalogStatus;
    enum        E2kGlobalCatalogLookupType;
    enum        E2kGlobalCatalogLookupFlags;
                E2kGlobalCatalogEntry;
    E2kGlobalCatalogStatus e2k_global_catalog_lookup
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 E2kGlobalCatalogLookupType type,
                                                 const char *key,
                                                 E2kGlobalCatalogLookupFlags flags,
                                                 E2kGlobalCatalogEntry **entry_p);
    #define     e2k_global_catalog_entry_free   (gc, entry)
    void        (*E2kGlobalCatalogCallback)     (E2kGlobalCatalog *gc,
                                                 E2kGlobalCatalogStatus status,
                                                 E2kGlobalCatalogEntry *entry,
                                                 gpointer user_data);
    void        e2k_global_catalog_async_lookup (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 E2kGlobalCatalogLookupType type,
                                                 const char *key,
                                                 E2kGlobalCatalogLookupFlags flags,
                                                 E2kGlobalCatalogCallback callback,
                                                 gpointer user_data);

    E2kGlobalCatalogStatus e2k_global_catalog_add_delegate
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 const char *self_dn,
                                                 const char *delegate_dn);
    E2kGlobalCatalogStatus e2k_global_catalog_remove_delegate
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 const char *self_dn,
                                                 const char *delegate_dn);

## Object Hierarchy

      GObject
       +----E2kGlobalCatalog

## Description

E2kGlobalCatalog represents a connection to the local Active Directory Global Catalog replica. The Global Catalog is replicated at each site in a Windows domain, and contains a subset of Active Directory information for every object in the entire Active Directory tree. (As opposed to the regular Active Directory servers, which contain complete information about only the local portion of the tree.)

Connector uses the global catalog for two major purposes:

- To populate the Global Address List

- To look up information about other users, such as what Exchange server their mail is on, or what their SID is.

## Details

### struct E2kGlobalCatalog

    struct E2kGlobalCatalog;

E2kGlobalCatalog manages connections to the Global Catalog server.

### e2k_global_catalog_new ()

    E2kGlobalCatalog* e2k_global_catalog_new    (const char *server,
                                                 int response_limit,
                                                 const char *user,
                                                 const char *domain,
                                                 const char *password);

Create an object for communicating with the Windows Global Catalog via LDAP.

`server` : | the GC server name
`response_limit` : | the maximum number of responses to return from a search
`user` : | username to authenticate with
`domain` : | NT domain of `user`, or `NULL` to autodetect.
`password` : | password to authenticate with
Returns : | the new E2kGlobalCatalog. (This call will always succeed. If the passed-in data is bad, it will fail on a later call.)

### e2k_global_catalog_get_ldap ()

    LDAP*       e2k_global_catalog_get_ldap     (E2kGlobalCatalog *gc,
                                                 E2kOperation *op);

Returns a new LDAP handle. The caller must `ldap_unbind()` it when it is done.

`gc` : | the global catalog
`op` : | pointer to an initialized E2kOperation to use for cancellation
Returns : | an LDAP handle, or `NULL` if it can't connect

### enum E2kGlobalCatalogStatus

    typedef enum {
    	E2K_GLOBAL_CATALOG_OK,
    	E2K_GLOBAL_CATALOG_NO_SUCH_USER,
    	E2K_GLOBAL_CATALOG_NO_DATA,
    	E2K_GLOBAL_CATALOG_BAD_DATA,
    	E2K_GLOBAL_CATALOG_EXISTS,
    	E2K_GLOBAL_CATALOG_AUTH_FAILED,
    	E2K_GLOBAL_CATALOG_CANCELLED,
    	E2K_GLOBAL_CATALOG_ERROR
    } E2kGlobalCatalogStatus;

The return status from an E2kGlobalCatalog function.

`E2K_GLOBAL_CATALOG_OK` | Success
`E2K_GLOBAL_CATALOG_NO_SUCH_USER` | User does not exist in Global Catalog
`E2K_GLOBAL_CATALOG_NO_DATA` | User exists, but the requested data does not. (Eg, if you ask for the email address of a non-mail-enabled user.)
`E2K_GLOBAL_CATALOG_BAD_DATA` | Data provided by caller was invalid
`E2K_GLOBAL_CATALOG_EXISTS` | Entry already exists (eg, when adding a delegate)
`E2K_GLOBAL_CATALOG_AUTH_FAILED` | Could not authenticate to Global Catalog
`E2K_GLOBAL_CATALOG_CANCELLED` | User cancelled request
`E2K_GLOBAL_CATALOG_ERROR` | Other error

### enum E2kGlobalCatalogLookupType

    typedef enum {
    	E2K_GLOBAL_CATALOG_LOOKUP_BY_EMAIL,
    	E2K_GLOBAL_CATALOG_LOOKUP_BY_DN,
    	E2K_GLOBAL_CATALOG_LOOKUP_BY_LEGACY_EXCHANGE_DN
    } E2kGlobalCatalogLookupType;

This indicates what field to compare the search key against when doing a lookup:

`E2K_GLOBAL_CATALOG_LOOKUP_BY_EMAIL` | Compare against the SMTP email address
`E2K_GLOBAL_CATALOG_LOOKUP_BY_DN` | Compare against the Active Directory Distinguished Name. (This is the fastest search key.)
`E2K_GLOBAL_CATALOG_LOOKUP_BY_LEGACY_EXCHANGE_DN` | Compare against the Exchange 5.5-style DN

### enum E2kGlobalCatalogLookupFlags

    typedef enum {
    	E2K_GLOBAL_CATALOG_LOOKUP_SID                = (1 << 0),
    	E2K_GLOBAL_CATALOG_LOOKUP_EMAIL              = (1 << 1),
    	E2K_GLOBAL_CATALOG_LOOKUP_MAILBOX            = (1 << 2),
    	E2K_GLOBAL_CATALOG_LOOKUP_LEGACY_EXCHANGE_DN = (1 << 3),
    	E2K_GLOBAL_CATALOG_LOOKUP_DELEGATES          = (1 << 4),
    	E2K_GLOBAL_CATALOG_LOOKUP_DELEGATORS         = (1 << 5),
    	E2K_GLOBAL_CATALOG_LOOKUP_QUOTA		     = (1 << 6),
    	E2K_GLOBAL_CATALOG_LOOKUP_ACCOUNT_CONTROL    = (1 << 7)
    } E2kGlobalCatalogLookupFlags;

This bitfield is used to indicate what data should be returned from a lookup:

`E2K_GLOBAL_CATALOG_LOOKUP_SID` | Look up the user’s SID
`E2K_GLOBAL_CATALOG_LOOKUP_EMAIL` | Look up the user’s email address
`E2K_GLOBAL_CATALOG_LOOKUP_MAILBOX` | Look up the location of the user’s Exchange mailbox
`E2K_GLOBAL_CATALOG_LOOKUP_LEGACY_EXCHANGE_DN` | Look up the user’s Exchange 5.5-style DN
`E2K_GLOBAL_CATALOG_LOOKUP_DELEGATES` | Look up the list of the user’s Exchange delegates
`E2K_GLOBAL_CATALOG_LOOKUP_DELEGATORS` | Look up the list of users who have made the indicated user their delegate
`E2K_GLOBAL_CATALOG_LOOKUP_QUOTA` | Look up the user's Exchange quote information
`E2K_GLOBAL_CATALOG_LOOKUP_ACCOUNT_CONTROL` |

### E2kGlobalCatalogEntry

    typedef struct {
    	char *dn, *display_name;
    	E2kSid *sid;
    	char *email, *exchange_server, *mailbox, *legacy_exchange_dn;
    	GPtrArray *delegates, *delegators;
    	int quota_warn, quota_nosend, quota_norecv;
    	int user_account_control;

    	E2kGlobalCatalogLookupFlags mask;
    } E2kGlobalCatalogEntry;

This represents the returned data from `e2k_global_catalog_lookup()` or `e2k_global_catalog_async_lookup()`.

The `dn`, `display_name`, `email`, and `legacy_exchange_dn` fields will be filled regardless of what fields are queried for. Other fields will only be filled in based on the `flags` passed to the lookup function.

char *`dn`; |
char *`display_name`; |
E2kSid *`sid`; | The SID (Windows Security Identifier) of the user.
char *`email`; |
char *`exchange_server`; |
char *`mailbox`; |
char *`legacy_exchange_dn`; |
GPtrArray *`delegates`; |
GPtrArray *`delegators`; |
int `quota_warn`; | the mailbox size (in kilobytes) at which the user should be warned about quota usage
int `quota_nosend`; | the mailbox size (in kilobytes) at which the user will no longer be allowed to send mail
int `quota_norecv`; | the mailbox size (in kilobytes) at which the user will no longer be able to receive mail.
int `user_account_control`; |
E2kGlobalCatalogLookupFlags `mask`; | indicates which other fields contain valid data

### e2k_global_catalog_lookup ()

    E2kGlobalCatalogStatus e2k_global_catalog_lookup
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 E2kGlobalCatalogLookupType type,
                                                 const char *key,
                                                 E2kGlobalCatalogLookupFlags flags,
                                                 E2kGlobalCatalogEntry **entry_p);

Look up the indicated user in the global catalog and return their information in *`entry_p`.

`gc` : | the global catalog
`op` : | pointer to an E2kOperation to use for cancellation
`type` : | the type of information in `key`
`key` : | email address or DN to look up
`flags` : | the information to look up
`entry_p` : | pointer to a variable to return the entry in.
Returns : | the status of the lookup

### e2k_global_catalog_entry_free()

    #define e2k_global_catalog_entry_free(gc, entry)

Frees `entry`. (This is currently actually a no-op, because `gc` caches the data forever.)

`gc` : | the global catalog
`entry` : | an entry

### E2kGlobalCatalogCallback ()

    void        (*E2kGlobalCatalogCallback)     (E2kGlobalCatalog *gc,
                                                 E2kGlobalCatalogStatus status,
                                                 E2kGlobalCatalogEntry *entry,
                                                 gpointer user_data);

The prototype of the callback function passed in to `e2k_global_catalog_async_lookup()`.

`gc` : | the global catalog
`status` : | the result of the lookup
`entry` : | on success, the requested data
`user_data` : | the `user_data` passed to `e2k_global_catalog_async_lookup()`

### e2k_global_catalog_async_lookup ()

    void        e2k_global_catalog_async_lookup (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 E2kGlobalCatalogLookupType type,
                                                 const char *key,
                                                 E2kGlobalCatalogLookupFlags flags,
                                                 E2kGlobalCatalogCallback callback,
                                                 gpointer user_data);

Asynchronously look up the indicated user in the global catalog and return the requested information to the callback.

`gc` : | the global catalog
`op` : | pointer to an E2kOperation to use for cancellation
`type` : | the type of information in `key`
`key` : | email address or DN to look up
`flags` : | the information to look up
`callback` : | the callback to invoke after finding the user
`user_data` : | data to pass to callback

### e2k_global_catalog_add_delegate ()

    E2kGlobalCatalogStatus e2k_global_catalog_add_delegate
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 const char *self_dn,
                                                 const char *delegate_dn);

Attempts to make `delegate_dn` a delegate of `self_dn`.

`gc` : | the global catalog
`op` : | pointer to an E2kOperation to use for cancellation
`self_dn` : | Active Directory DN of the user to add a delegate to
`delegate_dn` : | Active Directory DN of the new delegate
Returns : | `E2K_GLOBAL_CATALOG_OK` on success, `E2K_GLOBAL_CATALOG_NO_SUCH_USER` if `self_dn` is invalid, `E2K_GLOBAL_CATALOG_BAD_DATA` if `delegate_dn` is invalid, `E2K_GLOBAL_CATALOG_EXISTS` if `delegate_dn` is already a delegate, `E2K_GLOBAL_CATALOG_ERROR` on other errors.

### e2k_global_catalog_remove_delegate ()

    E2kGlobalCatalogStatus e2k_global_catalog_remove_delegate
                                                (E2kGlobalCatalog *gc,
                                                 E2kOperation *op,
                                                 const char *self_dn,
                                                 const char *delegate_dn);

Attempts to remove `delegate_dn` as a delegate of `self_dn`.

`gc` : | the global catalog
`op` : | pointer to an E2kOperation to use for cancellation
`self_dn` : | Active Directory DN of the user to remove a delegate from
`delegate_dn` : | Active Directory DN of the delegate to remove
Returns : | `E2K_GLOBAL_CATALOG_OK` on success, `E2K_GLOBAL_CATALOG_NO_SUCH_USER` if `self_dn` is invalid, `E2K_GLOBAL_CATALOG_NO_DATA` if `delegate_dn` is not a delegate of `self_dn`, `E2K_GLOBAL_CATALOG_ERROR` on other errors.

## See Also

E2kAutoconfig, E2kSid