summaryrefslogtreecommitdiffstats
path: root/mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl
diff options
context:
space:
mode:
Diffstat (limited to 'mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl')
-rw-r--r--mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl194
1 files changed, 194 insertions, 0 deletions
diff --git a/mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl b/mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl
new file mode 100644
index 000000000..8b07f68af
--- /dev/null
+++ b/mailnews/addrbook/public/nsIAbLDAPAttributeMap.idl
@@ -0,0 +1,194 @@
+/* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#include "nsISupports.idl"
+
+interface nsILDAPMessage;
+interface nsIAbCard;
+
+/**
+ * A mapping between addressbook properties and ldap attributes.
+ *
+ * Each addressbook property can map to one or more attributes. If
+ * there is no entry in preferences for a field, the getters generally
+ * return null; empty strings are passed through as usual. The intent is
+ * that properties with a non-zero number of attributes can be overridden for
+ * a specific server by supplying a zero-length string. For this to work,
+ * most callers are likely to want to check for both success and a
+ * non-empty string.
+ *
+ * Note that the one exception to this pattern is getAttributes, which
+ * throws NS_ERROR_FAILURE for non-existent property entries, since
+ * XPConnect doesn't like returning null arrays.
+ *
+ * Note that each LDAP attribute can map to at most one addressbook
+ * property. The checkState method is a useful tool in enforcing
+ * this. Failure to enforce it may make it impossible to guarantee
+ * that getProperty will do something consistent and reasonable.
+ *
+ * Maybe someday once we support ldap autoconfig stuff (ie
+ * draft-joslin-config-schema-11.txt), we can simplify this and other
+ * code and only allow a property to map to a single attribute.
+ */
+[scriptable, uuid(fa019fd1-7f3d-417a-8957-154cca0240be)]
+interface nsIAbLDAPAttributeMap : nsISupports
+{
+ /**
+ * Get all the LDAP attributes associated with a given property
+ * name, in order of precedence (highest to lowest).
+ *
+ * @param aProperty the address book property to return attrs for
+ *
+ * @return a comma-separated list of attributes, null if no entry is
+ * present
+ */
+ ACString getAttributeList(in ACString aProperty);
+
+ /**
+ * Get all the LDAP attributes associated with a given property name, in
+ * order of precedence (highest to lowest).
+ *
+ * @param aProperty the address book property to return attrs for
+ *
+ * @return an array of attributes
+ *
+ * @exception NS_ERROR_FAILURE if there is no entry for this property
+ */
+ void getAttributes(in ACString aProperty, out unsigned long aCount,
+ [retval, array, size_is(aCount)] out string aAttrs);
+
+ /**
+ * Get the first (canonical) LDAP attribute associated with a given property
+ * name
+ *
+ * @param aProperty the address book property to return attrs for
+ *
+ * @return the first attribute associated with a given property,
+ * null if there is no entry for this property
+ */
+ ACString getFirstAttribute(in ACString aProperty);
+
+ /**
+ * Set an existing mapping to the comma-separated list of attributes.
+ *
+ * @param aProperty the mozilla addressbook property name
+ *
+ * @param aAttributeList a comma-separated list of attributes in
+ * order of precedence from high to low
+ *
+ * @param aAllowInconsistencies allow changes that would result in
+ * a map with an LDAP attribute associated
+ * with more than one property. Useful for
+ * doing a bunch of sets at once, and
+ * calling checkState at the end.
+ *
+ * @exception NS_ERROR_FAILURE making this change would result in a map
+ * with an LDAP attribute pointing to more
+ * than one property
+ */
+ void setAttributeList(in ACString aProperty, in ACString aAttributeList,
+ in boolean allowInconsistencies);
+
+ /**
+ * Find the Mozilla addressbook property name that this attribute should
+ * map to.
+ *
+ * @return the addressbook property name, null if it's not used in the map
+ */
+ ACString getProperty(in ACString aAttribute);
+
+ /**
+ * Get all attributes that may be used in an addressbook card via this
+ * property map (used for passing to to an LDAP search when you want
+ * everything that could be in a card returned).
+ *
+ * @return a comma-separated list of attribute names
+ *
+ * @exception NS_ERROR_FAILURE there are no attributes in this property map
+ */
+ ACString getAllCardAttributes();
+
+ /**
+ * Get all properties that may be used in an addressbook card via this
+ * property map.
+ *
+ * @return an array of properties
+ *
+ * @exception NS_ERROR_FAILURE there are no attributes in this property map
+ */
+ void getAllCardProperties(out unsigned long aCount,
+ [retval, array, size_is(aCount)] out string aProps);
+
+ /**
+ * Check that no LDAP attributes are listed in more than one property.
+ *
+ * @exception NS_ERROR_FAILURE one or more LDAP attributes are listed
+ * multiple times. The object is now in an
+ * inconsistent state, and should be either
+ * manually repaired or discarded.
+ */
+ void checkState();
+
+ /* These last two methods are really just for the convenience of the caller
+ * and to avoid tons of unnecessary crossing of the XPConnect boundary.
+ */
+
+ /**
+ * Set any attributes specified in the given prefbranch on this object.
+ *
+ * @param aPrefBranchName the pref branch containing all the
+ * property names
+ *
+ * @exception NS_ERROR_FAILURE one or more LDAP attributes are listed
+ * multiple times. The object is now in an
+ * inconsistent state, and should be either
+ * manually repaired or discarded.
+ */
+ void setFromPrefs(in ACString aPrefBranchName);
+
+ /**
+ * Set the properties on an addressbook card from the given LDAP message
+ * using the map in this object.
+ *
+ * @param aCard is the card object whose values are to be set
+ * @param aMessage is the LDAP message to get the values from
+ *
+ * @exception NS_ERROR_FAILURE is thrown if no addressbook properties
+ * are found in the message
+ */
+ void setCardPropertiesFromLDAPMessage(in nsILDAPMessage aMessage,
+ in nsIAbCard aCard);
+};
+
+/**
+ * The nsIAbLDAPAttributeMapService is used to build and hold a cache
+ * of maps.
+ */
+[scriptable, uuid(12e2d589-3c2a-48e4-8c82-b1e6464a0dfd)]
+interface nsIAbLDAPAttributeMapService : nsISupports
+{
+ /**
+ * Accessor to construct or return a cached copy of the attribute
+ * map for a given preference branch. The map is constructed by
+ * first taking the default map (as specified by the
+ * "ldap_2.servers.default.attrmap" prefbranch), and then having any
+ * preferences specified by aPrefBranchName override the defaults.
+ * LDIF import and export code should use the default map.
+ *
+ * @return the requested map
+ *
+ * @exception NS_ERROR_FAILURE error constructing the map;
+ * possibly because of a failure
+ * from checkState()
+ */
+ nsIAbLDAPAttributeMap getMapForPrefBranch(in ACString aPrefBranchName);
+};
+
+
+%{C++
+// test whether one of the getters has actually found an attribute
+#define ATTRMAP_FOUND_ATTR(rv, str) (NS_SUCCEEDED(rv) && !(str).IsEmpty())
+%}