![]() | ![]() | ![]() | Ximian Connector for Microsoft Exchange Programmer’s Reference Manual | ![]() |
---|
E2kGlobalCatalog — Connection to the local Active Directory Global Catalog replica server
struct E2kGlobalCatalog; E2kGlobalCatalog* e2k_global_catalog_new (constchar *server,int response_limit, constchar *user, constchar *domain, constchar *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, constchar *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, constchar *key, E2kGlobalCatalogLookupFlags flags, E2kGlobalCatalogCallback callback,gpointer user_data); E2kGlobalCatalogStatus e2k_global_catalog_add_delegate (E2kGlobalCatalog *gc,E2kOperation *op, constchar *self_dn, constchar *delegate_dn); E2kGlobalCatalogStatus e2k_global_catalog_remove_delegate (E2kGlobalCatalog *gc,E2kOperation *op, constchar *self_dn, constchar *delegate_dn);
GObject +----E2kGlobalCatalog
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.
E2kGlobalCatalog* e2k_global_catalog_new (constchar *server,int response_limit, constchar *user, constchar *domain, constchar *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.) |
LDAP * e2k_global_catalog_get_ldap (E2kGlobalCatalog *gc,E2kOperation *op);
Returns a new LDAP handle. The caller must
gc : | the global catalog |
op : | pointer to an initialized |
Returns : | an LDAP handle, or NULL if it can't connect |
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_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 |
E2K_GLOBAL_CATALOG_AUTH_FAILED | |
E2K_GLOBAL_CATALOG_CANCELLED | |
E2K_GLOBAL_CATALOG_ERROR | Other error |
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 |
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_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 |
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().
dn | The Active Directory Distinguished Name of the result. |
display_name | The UTF-8 display name of the user queried for. |
sid | The SID (Windows Security Identifier) of the user. |
The user’s SMTP email address. | |
exchange_server | The user’s Exchange server. |
mailbox | The name of the user’s mailbox on exchange_server. |
legacy_exchange_dn | The user’s Exchange 5.5-style DN. |
delegates | An array of the Active Directory DNs of the user’s Exchange delegates. |
delegators | An 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.
E2kGlobalCatalogStatus e2k_global_catalog_lookup (E2kGlobalCatalog *gc,E2kOperation *op, E2kGlobalCatalogLookupType type, constchar *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 |
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 |
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() |
void e2k_global_catalog_async_lookup (E2kGlobalCatalog *gc,E2kOperation *op, E2kGlobalCatalogLookupType type, constchar *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 |
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 |
E2kGlobalCatalogStatus e2k_global_catalog_add_delegate (E2kGlobalCatalog *gc,E2kOperation *op, constchar *self_dn, constchar *delegate_dn);
Attempts to make delegate_dn a delegate of self_dn.
gc : | the global catalog |
op : | pointer to an |
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. |
E2kGlobalCatalogStatus e2k_global_catalog_remove_delegate (E2kGlobalCatalog *gc,E2kOperation *op, constchar *self_dn, constchar *delegate_dn);
Attempts to remove delegate_dn as a delegate of self_dn.
gc : | the global catalog |
op : | pointer to an |
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. |
<< e2k-properties | E2kUserDialog >> |