Back to index

lightning-sunbird  0.9+nobinonly
nsDirPrefs.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1999
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef _NSDIRPREFS_H_
00039 #define _NSDIRPREFS_H_
00040 
00041 class nsVoidArray;
00042 class nsIPref;
00043 
00044 #define kPreviousListVersion   2
00045 #define kCurrentListVersion    3
00046 #define PREF_LDAP_GLOBAL_TREE_NAME "ldap_2"
00047 #define PREF_LDAP_VERSION_NAME     "ldap_2.version"
00048 #define PREF_LDAP_SERVER_TREE_NAME "ldap_2.servers"
00049 
00050 /* RDF roor for all types of address books */
00051 /* use this to get all directories, create new directory*/
00052 #define kAllDirectoryRoot          "moz-abdirectory://" 
00053 
00054 #define kMDBDirectoryRoot          "moz-abmdbdirectory://"
00055 #define kMDBDirectoryRootLen       21
00056 
00057 #define kLDAPDirectoryRoot         "moz-abldapdirectory://"
00058 #define kLDAPDirectoryRootLen      22
00059 
00060 #define kPersonalAddressbook       "abook.mab"
00061 #define kPersonalAddressbookUri    "moz-abmdbdirectory://abook.mab"
00062 #define kCollectedAddressbook      "history.mab"
00063 #define kCollectedAddressbookUri   "moz-abmdbdirectory://history.mab"
00064 
00065 
00066 #define kABFileName_PreviousSuffix ".na2" /* final v2 address book format */
00067 #define kABFileName_PreviousSuffixLen 4
00068 #define kABFileName_CurrentSuffix ".mab"  /* v3 address book extension */
00069 #define kMainLdapAddressBook "ldap.mab"   /* v3 main ldap address book file */
00070 
00071 /* DIR_Server.dirType */
00072 typedef enum
00073 {
00074        LDAPDirectory,
00075        HTMLDirectory,
00076   PABDirectory,
00077   MAPIDirectory,
00078   FixedQueryLDAPDirectory = 777
00079 } DirectoryType;
00080 
00081 typedef enum
00082 {
00083        cn,
00084        givenname,
00085        sn,
00086        mail,
00087        telephonenumber,   /* work */
00088        o,
00089        ou,
00090        l,
00091        street,
00092        auth,
00093        /* mscott: I've added these extra DIR_AttributeIDs because the new address book can handle these */
00094        carlicense,
00095        businesscategory,
00096        departmentnumber,
00097        description,
00098        employeetype,
00099        facsimiletelephonenumber,
00100        /* jpegPhoto */
00101        manager,
00102        objectclass,
00103        postaladdress,
00104        postalcode,
00105        secretary,
00106        title,
00107        custom1,
00108        custom2,
00109        custom3,
00110        custom4,
00111        custom5, 
00112        nickname, /* only valid on address book directories as LDAP does not have a nick name field */
00113        mobiletelephonenumber,  /* cell phone */
00114        pager,
00115        homephone
00116 } DIR_AttributeId;
00117 
00118 /* these enumerated types are returned by DIR_ValidateDirectoryDescription for validating a description name */
00119 typedef enum
00120 {
00121        DIR_ValidDescription = 0,
00122        DIR_DuplicateDescription,
00123        DIR_InvalidDescription
00124 } DIR_DescriptionCode;
00125 
00126 typedef enum
00127 {
00128        idNone = 0,                               /* Special value                          */ 
00129        idPrefName,
00130        idPosition, 
00131        idRefCount,
00132        idDescription,
00133        idServerName,
00134        idSearchBase,
00135        idFileName,
00136        idPort,
00137        idMaxHits,
00138        idUri,
00139        idLastSearchString,
00140        idType,       
00141        idCSID,
00142        idLocale,
00143        idPositionLocked,
00144        idDeletable,
00145        idStopFiltersOnHit,
00146        idIsOffline,
00147        idIsSecure,
00148        idVLVDisabled,
00149        idSaveResults,
00150        idEfficientWildcards,
00151        idEnableAuth,
00152        idSavePassword,
00153        idCustomFilters,
00154        idCustomAttributes,
00155        idAutoCompleteNever,
00156        idAutoCompleteEnabled,
00157        idAutoCompleteFilter,
00158        idTokenSeps,
00159        idColumnAttributes,
00160        idDnAttributes,
00161     idDnAttributesCount,
00162        idSuppressedAttributes,
00163        idSuppressedAttributesCount,
00164        idUriAttributes,
00165        idUriAttributesCount,
00166        idBasicSearchAttributes,
00167        idBasicSearchAttributesCount,
00168        idCustomDisplayUrl,
00169        idAuthDn,
00170        idPassword,
00171        idSearchPairList,
00172        idReplNever,
00173        idReplEnabled,
00174        idReplDescription,
00175        idReplFileName,
00176        idReplFilter,
00177        idReplLastChangeNumber,
00178        idReplDataVersion,
00179        idReplSyncURL,
00180        idReplExcludedAttributes,
00181        idReplExcludedAttributesCount,
00182        idPalmCategory,
00183         idPalmSyncTimeStamp,
00184         idProtocolVersion
00185 } DIR_PrefId;
00186 
00187 
00188 typedef struct _DIR_ReplicationInfo
00189 
00190 {
00191        char *description;           /* Human readable description of replica                */
00192        char *fileName;              /* File name of replication database                    */
00193        char *filter;                /* LDAP filter string which constrains the repl search  */
00194        PRInt32 lastChangeNumber;      /* Last change we saw -- start replicating here         */
00195        char *syncURL;               /* Points to the server to use for replication          */
00196        char *dataVersion;           /* LDAP server's scoping of the lastChangeNumber        */
00197                                     /* Changes when the server's DB gets reloaded from LDIF */
00198        char **excludedAttributes;   /* List of attributes we shouldn't replicate            */
00199        PRInt32 excludedAttributesCount; /* Number of attributes we shouldn't replicat           */
00200 } DIR_ReplicationInfo;
00201 
00202 #define DIR_Server_typedef 1     /* this quiets a redeclare warning in libaddr */
00203 
00204 typedef struct DIR_Server
00205 {
00206        /* Housekeeping fields */
00207        char   *prefName;                  /* preference name, this server's subtree */
00208        PRInt32  position;                 /* relative position in server list       */
00209        PRUint32  refCount;         /* Use count for server                   */
00210 
00211        /* General purpose fields */
00212        char   *description;        /* human readable name                    */
00213        char   *serverName;             /* network host name                      */
00214        char   *searchBase;             /* DN suffix to search at                 */
00215        char   *fileName;                  /* XP path name of local DB               */
00216        PRInt32 port;                      /* network port number                    */
00217        PRInt32 maxHits;                   /* maximum number of hits to return       */
00218        char   *lastSearchString;   /* required if saving results             */
00219        DirectoryType dirType;      
00220        PRInt16   csid;                           /* LDAP entries' codeset (normally UTF-8) */
00221        char    *locale;                   /* the locale associated with the address book or directory */
00222     char    *uri;       // URI of the address book
00223 
00224        /* Flags */
00225        /* TBD: All the PRBool fields should eventually merge into "flags" */
00226        PRUint32 flags;               
00227        PRPackedBool stopFiltersOnHit;
00228        PRPackedBool isOffline;
00229        PRPackedBool isSecure;           /* use SSL?                               */
00230        PRPackedBool saveResults;    
00231        PRPackedBool efficientWildcards; /* server can match substrings            */
00232        PRPackedBool enableAuth;                  /* AUTH: Use DN/password when binding?    */
00233        PRPackedBool savePassword;         /* AUTH: Remember DN and password?        */
00234 
00235        /* site-configurable attributes and filters */
00236        nsVoidArray *customFilters;
00237        nsVoidArray *customAttributes;
00238        char *tokenSeps;
00239        char *autoCompleteFilter;
00240 
00241        /* site-configurable display column attributes */
00242        char *columnAttributes;     /* comma separated list of display columns */
00243 
00244        /* site-configurable list of attributes whose values are DNs */
00245        char **dnAttributes;
00246     PRInt32 dnAttributesCount;
00247 
00248        /* site-configurable list of attributes we shouldn't display in HTML */
00249        char **suppressedAttributes;
00250        PRInt32 suppressedAttributesCount;
00251 
00252        /* site-configurable list of attributes that contain URLs */
00253        char **uriAttributes;
00254        PRInt32 uriAttributesCount;
00255 
00256        /* site-configurable list of attributes for the Basic Search dialog */
00257        DIR_AttributeId *basicSearchAttributes;
00258        PRInt32 basicSearchAttributesCount;
00259 
00260        /* site-configurable URL to open LDAP results */
00261        char *customDisplayUrl;
00262 
00263        /* authentication fields */
00264        char *authDn;                      /* DN to give to authenticate as                 */
00265        char *password;                           /* Password for the DN                                         */
00266 
00267        /* Replication fields */
00268        DIR_ReplicationInfo *replInfo;
00269 
00270        /* VLV fields */
00271        char *searchPairList;
00272 
00273        /* fields for palm Sync */
00274        PRInt32 PalmCategoryId;
00275        PRUint32 PalmSyncTimeStamp;
00276 } DIR_Server;
00277 
00278 /* We are developing a new model for managing DIR_Servers. In the 4.0x world, the FEs managed each list. 
00279        Calls to FE_GetDirServer caused the FEs to manage and return the DIR_Server list. In our new view of the
00280        world, the back end does most of the list management so we are going to have the back end create and 
00281        manage the list. Replace calls to FE_GetDirServers() with DIR_GetDirServers(). */
00282 
00283 nsVoidArray* DIR_GetDirectories();
00284 nsresult DIR_GetDirServers();
00285 nsresult DIR_ShutDown(void);  /* FEs should call this when the app is shutting down. It frees all DIR_Servers regardless of ref count values! */
00286 
00287 nsresult DIR_AddNewAddressBook(const PRUnichar *dirName, const char *fileName, PRBool migrating, const char * uri, int maxHits, const char * authDn, DirectoryType dirType, DIR_Server** pServer);
00288 nsresult DIR_ContainsServer(DIR_Server* pServer, PRBool *hasDir);
00289 
00290 nsresult DIR_DecrementServerRefCount (DIR_Server *);
00291 nsresult DIR_IncrementServerRefCount (DIR_Server *);
00292 
00293 /* We are trying to phase out use of FE_GetDirServers. The back end is now managing the dir server list. So you should
00294        be calling DIR_GetDirServers instead. */
00295 
00296 nsVoidArray * FE_GetDirServers(void);
00297 
00298 /* Since the strings in DIR_Server are allocated, we have bottleneck
00299  * routines to help with memory mgmt
00300  */
00301 
00302 nsresult DIR_InitServerWithType(DIR_Server * server, DirectoryType dirType);
00303 nsresult DIR_InitServer (DIR_Server *);
00304 nsresult DIR_CopyServer (DIR_Server *in, DIR_Server **out);
00305 PRBool DIR_AreServersSame (DIR_Server *first, DIR_Server *second);
00306 DIR_Server *DIR_LookupServer(char *serverName, PRInt32 port, char *searchBase);
00307 
00308 nsresult DIR_DeleteServer (DIR_Server *);
00309 nsresult DIR_DeleteServerFromList (DIR_Server *);
00310 nsresult DIR_DeleteServerList(nsVoidArray *wholeList);
00311 
00312 #define DIR_POS_APPEND                     0x80000000
00313 #define DIR_POS_DELETE                     0x80000001
00314 PRBool DIR_SetServerPosition(nsVoidArray *wholeList, DIR_Server *server, PRInt32 position);
00315 
00316 /* These two routines should be called to initialize and save 
00317  * directory preferences from the XP Java Script preferences
00318  */
00319 nsresult DIR_GetServerPreferences(nsVoidArray** list);
00320 nsresult DIR_SaveServerPreferences(nsVoidArray *wholeList);
00321 void    DIR_GetPrefsForOneServer(DIR_Server *server, PRBool reinitialize, PRBool oldstyle);
00322 void    DIR_SavePrefsForOneServer(DIR_Server *server);
00323 
00324 /* This routine will clean up files for deleted directories */
00325 
00326 /* you should never need to call this function!!! Just set the clear
00327        flag for the entry you want cleaned up. When all references to
00328        the server are released, the object will be cleaned up */
00329 nsresult DIR_CleanUpServerPreferences(nsVoidArray *deletedList);
00330 void    DIR_ClearPrefBranch(const char *branch);
00331 
00332 /* Returns an allocated list of a subset of the unified list of DIR servers.
00333  */
00334 nsresult DIR_GetDirServerSubset(nsVoidArray *wholeList, nsVoidArray *subList, PRUint32 flags);
00335 PRInt32  DIR_GetDirServerSubsetCount(nsVoidArray *wholeList, PRUint32 flags);
00336 
00337 /* We need to validate directory descriptions to make sure they are unique. They can use this API for that */
00338 DIR_DescriptionCode DIR_ValidateDirectoryDescription(nsVoidArray * wholeList, DIR_Server * serverToValidate);
00339 
00340 char   *DIR_CreateServerPrefName (DIR_Server *server, char *name);
00341 void   DIR_SetServerFileName(DIR_Server* pServer, const char* leafName);
00342 
00343 /* APIs for site-configurability of LDAP attribute names and 
00344  * search filter behavior.
00345  *
00346  * Strings are NOT allocated, and arrays are NULL-terminated
00347  */
00348 const char  *DIR_GetAttributeName (DIR_Server *server, DIR_AttributeId id);
00349 const char **DIR_GetAttributeStrings (DIR_Server *server, DIR_AttributeId id);
00350 const char  *DIR_GetFirstAttributeString (DIR_Server *server, DIR_AttributeId id);
00351 const char  *DIR_GetFilterString (DIR_Server *server);
00352 const char  *DIR_GetReplicationFilter (DIR_Server *server);
00353 const char  *DIR_GetTokenSeparators (DIR_Server *server);
00354 PRBool      DIR_RepeatFilterForTokens (DIR_Server *server, const char *filter);
00355 PRBool      DIR_SubstStarsForSpaces (DIR_Server *server, const char *filter);
00356 PRBool       DIR_UseCustomAttribute (DIR_Server *server, DIR_AttributeId id);
00357 
00358 PRBool      DIR_IsDnAttribute (DIR_Server *s, const char *attr);
00359 PRBool      DIR_IsAttributeExcludedFromHtml (DIR_Server *s, const char *attr);
00360 PRBool      DIR_IsUriAttribute (DIR_Server *s, const char *attrib);
00361 
00362 nsresult DIR_AttributeNameToId (DIR_Server *server, const char *attrName, DIR_AttributeId *id);
00363 
00364 /* APIs for authentication */
00365 void          DIR_SetAuthDN (DIR_Server *s, const char *dn);
00366 void          DIR_SetPassword (DIR_Server *s, const char *password);
00367 
00368 /* APIs for unescaping LDAP special chars */
00369 char   *DIR_Unescape (const char *src, PRBool makeHtml);
00370 PRBool DIR_IsEscapedAttribute (DIR_Server *s, const char *attrib);
00371 
00372 /* API for building a URL */
00373 char *DIR_BuildUrl (DIR_Server *s, const char *dn, PRBool forAddToAB);
00374 
00375 /* Walks the list enforcing the rule that only one LDAP server can be configured for autocomplete */
00376 void DIR_SetAutoCompleteEnabled (nsVoidArray *list, DIR_Server *server, PRBool enabled);
00377 
00378 /* Callback Notification Flags/Types/Functions */
00379 #define DIR_NOTIFY_ADD                     0x00000001 
00380 #define DIR_NOTIFY_DELETE                  0x00000002 
00381 #define DIR_NOTIFY_PROPERTY_CHANGE         0x00000004 
00382 #define DIR_NOTIFY_SCRAMBLE                0x00000008 
00383 #define DIR_NOTIFY_ALL                     0x0000000F 
00384 
00385 typedef PRInt32 (*DIR_NOTIFICATION_FN)(DIR_Server *server, PRUint32 flag, DIR_PrefId id, void *inst_data);
00386 
00387 PRBool DIR_RegisterNotificationCallback(DIR_NOTIFICATION_FN fn, PRUint32 flags, void *inst_data);
00388 PRBool DIR_DeregisterNotificationCallback(DIR_NOTIFICATION_FN fn, void *inst_data);
00389 PRBool DIR_SendNotification(DIR_Server *server, PRUint32 flag, DIR_PrefId id);
00390 
00391 DIR_PrefId  DIR_AtomizePrefName(const char *prefname);
00392 char       *DIR_CopyServerStringPref(DIR_Server *server, DIR_PrefId prefid, PRInt16 csid);
00393 PRBool     DIR_SetServerStringPref(DIR_Server *server, DIR_PrefId prefid, char *pref, PRInt16 csid);
00394 
00395 /* Flags manipulation
00396  */
00397 #define DIR_AUTO_COMPLETE_ENABLED          0x00000001  /* Directory is configured for autocomplete addressing */
00398 #define DIR_ENABLE_AUTH                    0x00000002  /* Directory is configured for LDAP simple authentication */
00399 #define DIR_SAVE_PASSWORD                  0x00000004
00400 #define DIR_IS_SECURE                      0x00000008
00401 #define DIR_SAVE_RESULTS                   0x00000010  /* not used by the FEs */
00402 #define DIR_EFFICIENT_WILDCARDS            0x00000020  /* not used by the FEs */
00403 #define DIR_LDAP_VERSION3                  0x00000040
00404 #define DIR_LDAP_VLV_DISABLED              0x00000080  /* not used by the FEs */
00405 #define DIR_LDAP_VLV_SUPPORTED             0x00000100  /* not used by the FEs */
00406 #define DIR_LDAP_ROOTDSE_PARSED            0x00000200  /* not used by the FEs */
00407 #define DIR_AUTO_COMPLETE_NEVER            0x00000400  /* Directory is never to be used for autocompletion */
00408 #define DIR_REPLICATION_ENABLED            0x00000800  /* Directory is configured for offline use */
00409 #define DIR_REPLICATE_NEVER                0x00001000  /* Directory is never to be replicated */
00410 #define DIR_UNDELETABLE                    0x00002000
00411 #define DIR_POSITION_LOCKED                0x00004000
00412 
00413 /* The following flags are not used by the FEs.  The are operational flags
00414  * that get set in occasionally to keep track of special states.
00415  */
00416 /* Set when a DIR_Server is being saved.  Keeps the pref callback code from
00417  * reinitializing the DIR_Server structure, which in this case would always
00418  * be a waste of time.
00419  */
00420 #define DIR_SAVING_SERVER                  0x40000000
00421 /* Set by back end when all traces of the DIR_Server need to be removed (i.e.
00422  * destroying the file) when the last reference to to the DIR_Server is
00423  * released.  This is used primarily when the user decides to delete the
00424  * DIR_Server but it is referenced by other objects.  When no one is using the
00425  * dir server anymore, we destroy the file and clear the server
00426  */
00427 #define DIR_CLEAR_SERVER                            0x80000000  
00428 
00429 
00430 /* DIR_GetDirServerSubset flags
00431  */
00432 #define DIR_SUBSET_HTML_ALL                0x00000001
00433 #define DIR_SUBSET_LDAP_ALL                0x00000002
00434 #define DIR_SUBSET_LDAP_AUTOCOMPLETE       0x00000004
00435 #define DIR_SUBSET_LDAP_REPLICATE          0x00000008
00436 #define DIR_SUBSET_PAB_ALL                 0x00000010
00437 
00438 
00439 PRBool DIR_TestFlag  (DIR_Server *server, PRUint32 flag);
00440 void    DIR_SetFlag   (DIR_Server *server, PRUint32 flag);
00441 void    DIR_ClearFlag (DIR_Server *server, PRUint32 flag);
00442 void    DIR_ForceFlag (DIR_Server *server, PRUint32 flag, PRBool forceOnOrOff);
00443 
00444 char *DIR_ConvertToServerCharSet   (DIR_Server *s, char *src, PRInt16 srcCsid);
00445 char *DIR_ConvertFromServerCharSet (DIR_Server *s, char *src, PRInt16 dstCsid);
00446 char *DIR_ConvertString(PRInt16 srcCSID, PRInt16 dstCSID, const char *string);
00447 
00448 #endif /* dirprefs.h */