1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
2 *
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * The Original Code is mozilla addressbook code.
17 *
18 * The Initial Developer of the Original Code is Oracle Corporation.
19 * Portions created by the Initial Developer are Copyright (C) 2005
20 * the Initial Developer. All Rights Reserved.
21 *
22 * Contributor(s):
23 * Dan Mosedale <dan.mosedale@oracle.com>
24 * Jeremy Laine <jeremy.laine@m4x.org>
25 *
26 * Alternatively, the contents of this file may be used under the terms of
27 * either the GNU General Public License Version 2 or later (the "GPL"), or
28 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
29 * in which case the provisions of the GPL or the LGPL are applicable instead
30 * of those above. If you wish to allow use of your version of this file only
31 * under the terms of either the GPL or the LGPL, and not to allow others to
32 * use your version of this file under the terms of the MPL, indicate your
33 * decision by deleting the provisions above and replace them with the notice
34 * and other provisions required by the GPL or the LGPL. If you do not delete
35 * the provisions above, a recipient may use your version of this file under
36 * the terms of any one of the MPL, the GPL or the LGPL.
37 *
38 * ***** END LICENSE BLOCK ***** */
39
40 #include "nsISupports.idl"
41
42 interface nsISimpleEnumerator;
43 interface nsILDAPMessage;
44 interface nsIAbCard;
45
46 /**
47 * A mapping between addressbook properties and ldap attributes.
48 *
49 * Each addressbook property can map to one or more attributes. If
50 * there is no entry in preferences for a field, the getters generally
51 * return null; empty strings are passed through as usual. The intent is
52 * that properties with a non-zero number of attributes can be overridden for
53 * a specific server by supplying a zero-length string. For this to work,
54 * most callers are likely to want to check for both success and a
55 * non-empty string.
56 *
57 * Note that the one exception to this pattern is getAttributes, which
58 * throws NS_ERROR_FAILURE for non-existent property entries, since
59 * XPConnect doesn't like returning null arrays.
60 *
61 * Note that each LDAP attribute can map to at most one addressbook
62 * property. The checkState method is a useful tool in enforcing
63 * this. Failure to enforce it may make it impossible to guarantee
64 * that getProperty will do something consistent and reasonable.
65 *
66 * Maybe someday once we support ldap autoconfig stuff (ie
67 * draft-joslin-config-schema-11.txt), we can simplify this and other
68 * code and only allow a property to map to a single attribute.
69 */
70 [scriptable, uuid(bc543118-db5d-4616-b2d4-9a8667609a7c)]
71 interface nsIAbLDAPAttributeMap : nsISupports
72 {
73 /**
74 * Get all the LDAP attributes associated with a given property
75 * name, in order of precedence (highest to lowest).
76 *
77 * @param aProperty the address book property to return attrs for
78 *
79 * @return a comma-separated list of attributes, null if no entry is
80 * present
81 */
82 ACString getAttributeList(in ACString aProperty);
83
84 /**
85 * Get all the LDAP attributes associated with a given property name, in
86 * order of precedence (highest to lowest).
87 *
88 * @param aProperty the address book property to return attrs for
89 *
90 * @return an array of attributes
91 *
92 * @exception NS_ERROR_FAILURE if there is no entry for this property
93 */
94 void getAttributes(in ACString aProperty, out unsigned long aCount,
95 [retval, array, size_is(aCount)] out string aAttrs);
96
97 /**
98 * Get the first (canonical) LDAP attribute associated with a given property
99 * name
100 *
101 * @param aProperty the address book property to return attrs for
102 *
103 * @return the first attribute associated with a given property,
104 * null if there is no entry for this property
105 */
106 ACString getFirstAttribute(in ACString aProperty);
107
108 /**
109 * Set an existing mapping to the comma-separated list of attributes.
110 *
111 * @param aProperty the mozilla addressbook property name
112 *
113 * @param aAttributeList a comma-separated list of attributes in
114 * order of precedence from high to low
115 *
116 * @param aAllowInconsistencies allow changes that would result in
117 * a map with an LDAP attribute associated
118 * with more than one property. Useful for
119 * doing a bunch of sets at once, and
120 * calling checkState at the end.
121 *
122 * @exception NS_ERROR_FAILURE making this change would result in a map
123 * with an LDAP attribute pointing to more
124 * than one property
125 */
126 void setAttributeList(in ACString aProperty, in ACString aAttributeList,
127 in boolean allowInconsistencies);
128
129 /**
130 * Find the Mozilla addressbook property name that this attribute should
131 * map to.
132 *
133 * @return the addressbook property name, null if it's not used in the map
134 */
135 ACString getProperty(in ACString aAttribute);
136
137 /**
138 * Get all attributes that may be used in an addressbook card via this
139 * property map (used for passing to to an LDAP search when you want
140 * everything that could be in a card returned).
141 *
142 * @return a comma-separated list of attribute names
143 *
144 * @exception NS_ERROR_FAILURE there are no attributes in this property map
145 */
146 ACString getAllCardAttributes();
147
148 /**
149 * Get all properties that may be used in an addressbook card via this
150 * property map.
151 *
152 * @return an array of properties
153 *
154 * @exception NS_ERROR_FAILURE there are no attributes in this property map
155 */
156 void getAllCardProperties(out unsigned long aCount,
157 [retval, array, size_is(aCount)] out string aProps);
158
159 /**
160 * Check that no LDAP attributes are listed in more than one property.
161 *
162 * @exception NS_ERROR_FAILURE one or more LDAP attributes are listed
163 * multiple times. The object is now in an
164 * inconsistent state, and should be either
165 * manually repaired or discarded.
166 */
167 void checkState();
168
169 /* These last two methods are really just for the convenience of the caller
170 * and to avoid tons of unnecessary crossing of the XPConnect boundary.
171 */
172
173 /**
174 * Set any attributes specified in the given prefbranch on this object.
175 *
176 * @param aPrefBranchName the pref branch containing all the
177 * property names
178 *
179 * @exception NS_ERROR_FAILURE one or more LDAP attributes are listed
180 * multiple times. The object is now in an
181 * inconsistent state, and should be either
182 * manually repaired or discarded.
183 */
184 void setFromPrefs(in ACString aPrefBranchName);
185
186 /**
187 * Set the properties on an addressbook card from the given LDAP message
188 * using the map in this object.
189 *
190 * @param aCard is the card object whose values are to be set
191 * @param aMessage is the LDAP message to get the values from
192 *
193 * @exception NS_ERROR_FAILURE is thrown if no addressbook properties
194 * are found in the message
195 */
196 void setCardPropertiesFromLDAPMessage(in nsILDAPMessage aMessage,
197 in nsIAbCard aCard);
198 };
199
200 /**
201 * The nsIAbLDAPAttributeMapService is used to build and hold a cache
202 * of maps.
203 */
204 [scriptable, uuid(12e2d589-3c2a-48e4-8c82-b1e6464a0dfd)]
205 interface nsIAbLDAPAttributeMapService : nsISupports
206 {
207 /**
208 * Accessor to construct or return a cached copy of the attribute
209 * map for a given preference branch. The map is constructed by
210 * first taking the default map (as specified by the
211 * "ldap_2.servers.default.attrmap" prefbranch), and then having any
212 * preferences specified by aPrefBranchName override the defaults.
213 * LDIF import and export code should use the default map.
214 *
215 * @return the requested map
216 *
217 * @exception NS_ERROR_FAILURE error constructing the map;
218 * possibly because of a failure
219 * from checkState()
220 */
221 nsIAbLDAPAttributeMap getMapForPrefBranch(in ACString aPrefBranchName);
222 };
223
224
225 %{C++
226 // test whether one of the getters has actually found an attribute
227 #define ATTRMAP_FOUND_ATTR(rv, str) (NS_SUCCEEDED(rv) && !(str).IsEmpty())
228 %}