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;
struct      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;


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;

E2K_GLOBAL_CATALOG_OKSuccess
E2K_GLOBAL_CATALOG_NO_SUCH_USERUser does not exist in Global Catalog
E2K_GLOBAL_CATALOG_NO_DATAUser 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_DATAData provided by caller was invalid
E2K_GLOBAL_CATALOG_EXISTSEntry already exists
E2K_GLOBAL_CATALOG_AUTH_FAILED
E2K_GLOBAL_CATALOG_CANCELLED
E2K_GLOBAL_CATALOG_ERROROther 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_EMAILCompare against the SMTP email address
E2K_GLOBAL_CATALOG_LOOKUP_BY_DNCompare against the Active Directory Distinguished Name. (This is the fastest search key.)
E2K_GLOBAL_CATALOG_LOOKUP_BY_LEGACY_EXCHANGE_DNCompare 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),
} E2kGlobalCatalogLookupFlags;

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

E2K_GLOBAL_CATALOG_LOOKUP_SIDLook up the user’s SID
E2K_GLOBAL_CATALOG_LOOKUP_EMAILLook up the user’s email address
E2K_GLOBAL_CATALOG_LOOKUP_MAILBOXLook up the location of the user’s Exchange mailbox
E2K_GLOBAL_CATALOG_LOOKUP_LEGACY_EXCHANGE_DNLook up the user’s Exchange 5.5-style DN
E2K_GLOBAL_CATALOG_LOOKUP_DELEGATESLook up the list of the user’s Exchange delegates
E2K_GLOBAL_CATALOG_LOOKUP_DELEGATORSLook up the list of users who have made the indicated user their delegate
E2K_GLOBAL_CATALOG_LOOKUP_QUOTA

struct E2kGlobalCatalogEntry

struct E2kGlobalCatalogEntry {

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

	E2kGlobalCatalogLookupFlags mask;
};

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

dnThe Active Directory Distinguished Name of the result.
display_nameThe UTF-8 display name of the user queried for.
sidThe SID (Windows Security Identifier) of the user.
emailThe user’s SMTP email address.
exchange_serverThe user’s Exchange server.
mailboxThe name of the user’s mailbox on exchange_server.
legacy_exchange_dnThe user’s Exchange 5.5-style DN.
delegatesAn array of the Active Directory DNs of the user’s Exchange delegates.
delegatorsAn array of the Active Directory DNs of the users who have delegated to the searched-for user.

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.


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)

gc :
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