home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / include / msg_srch.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  17.9 KB  |  448 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18. /* 
  19.  * Public API for searching mail, news, and LDAP 
  20.  * pieces of this API are also used by filter rules and address book
  21.  * 
  22.  */
  23.  
  24. #ifndef _MSG_SRCH_H
  25. #define _MSG_SRCH_H
  26.  
  27. #include "msgcom.h"   /* for MSG_PRIORITY, MessageKey */
  28. #include "dirprefs.h" /* for DIR_AttributeId */
  29.  
  30. #define FE_IMPLEMENTS_BOOLEAN_OR
  31. #define B3_SEARCH_API
  32.  
  33. typedef enum
  34. {
  35.     SearchError_First,    /* no functions return this; just for bookkeeping    */
  36.     SearchError_Success,              /* no error                            */
  37.     SearchError_NotImplemented,       /* coming soon                         */
  38.  
  39.     SearchError_OutOfMemory,          /* can't allocate required memory      */
  40.     SearchError_NullPointer,          /* a req'd pointer parameter was null  */
  41.     SearchError_ScopeAgreement,       /* attr or op not supp in this scope   */
  42.     SearchError_ListTooSmall,         /* menu item array not big enough      */
  43.  
  44.     SearchError_ResultSetEmpty,       /* search done, no matches found       */
  45.     SearchError_ResultSetTooBig,      /* too many matches to get them all    */
  46.  
  47.     SearchError_InvalidAttribute,     /* specified attrib not in enum        */
  48.     SearchError_InvalidScope,         /* specified scope not in enum         */
  49.     SearchError_InvalidOperator,      /* specified op not in enum            */
  50.     
  51.     SearchError_InvalidSearchTerm,    /* cookie for search term is bogus     */
  52.     SearchError_InvalidScopeTerm,     /* cookie for scope term is bogus      */
  53.     SearchError_InvalidResultElement, /* cookie for result element is bogus  */
  54.     SearchError_InvalidPane,          /* context probably bogus              */
  55.     SearchError_InvalidStream,        /* in strm bad (too short? bad magic?) */
  56.     SearchError_InvalidFolder,        /* given folderInfo isn't searchable   */
  57.     SearchError_InvalidIndex,         /* the passed index is invalid         */
  58.  
  59.     SearchError_HostNotFound,         /* couldn't connect to server          */
  60.     SearchError_Timeout,              /* network didn't respond              */
  61.     SearchError_DBOpenFailed,         /* couldn't open off-line msg db       */
  62.  
  63.     SearchError_NotAMatch,            /* used internally for term eval       */
  64.     SearchError_ScopeDone,            /* used internally for scope list eval */
  65.  
  66.     SearchError_Unknown,              /* some random error                   */
  67.  
  68.     SearchError_Last      /* no functions return this; just for bookkeeping  */
  69. } MSG_SearchError;
  70.  
  71. typedef enum
  72. {
  73.     scopeMailFolder,
  74.     scopeNewsgroup,
  75.     scopeLdapDirectory,
  76.     scopeOfflineNewsgroup,
  77.     scopeAllSearchableGroups
  78. } MSG_ScopeAttribute;
  79.  
  80. /* NB: If you add elements to this enum, add only to the end, since 
  81.  *     RULES.DAT stores enum values persistently
  82.  */
  83. typedef enum
  84. {
  85.     attribSender = 0,   /* mail and news */
  86.     attribSubject,    
  87.     attribBody,    
  88.     attribDate,    
  89.  
  90.     attribPriority,        /* mail only */
  91.     attribMsgStatus,    
  92.     attribTo,
  93.     attribCC,
  94.     attribToOrCC,
  95.  
  96.     attribCommonName,   /* LDAP only */
  97.     attrib822Address,    
  98.     attribPhoneNumber,
  99.     attribOrganization,
  100.     attribOrgUnit,
  101.     attribLocality,
  102.     attribStreetAddress,
  103.     attribSize,
  104.     attribAnyText,      /* any header or body */
  105.     attribKeywords,
  106.  
  107.     attribDistinguishedName, /* LDAP result elem only */
  108.     attribObjectClass,       
  109.     attribJpegFile,
  110.  
  111.     attribLocation,          /* result list only */
  112.     attribMessageKey,        /* message result elems */
  113.  
  114.     attribAgeInDays,    /* for purging old news articles */
  115.  
  116.     attribGivenName,    /* for sorting LDAP results */
  117.     attribSurname, 
  118.  
  119.     attribFolderInfo,    /* for "view thread context" from result */
  120.  
  121.     attribCustom1,        /* custom LDAP attributes */
  122.     attribCustom2,
  123.     attribCustom3,
  124.     attribCustom4,
  125.     attribCustom5,
  126.  
  127.     attribMessageId, 
  128.     attribOtherHeader,  /* for mail and news. MUST ALWAYS BE LAST attribute since we can have an arbitrary # of these...*/
  129.  
  130.     kNumAttributes      /* must be last attribute */
  131. } MSG_SearchAttribute;
  132.  
  133. /* NB: If you add elements to this enum, add only to the end, since 
  134.  *     RULES.DAT stores enum values persistently
  135.  */
  136. typedef enum
  137. {
  138.     opContains = 0,     /* for text attributes              */
  139.     opDoesntContain,
  140.     opIs,               /* is and isn't also apply to some non-text attrs */
  141.     opIsnt, 
  142.     opIsEmpty,
  143.  
  144.     opIsBefore,         /* for date attributes              */
  145.     opIsAfter,
  146.     
  147.     opIsHigherThan,     /* for priority. opIs also applies  */
  148.     opIsLowerThan,
  149.  
  150.     opBeginsWith,              
  151.     opEndsWith,
  152.  
  153.     opSoundsLike,       /* for LDAP phoenetic matching      */
  154.     opLdapDwim,         /* Do What I Mean for simple search */
  155.  
  156.     opIsGreaterThan,    
  157.     opIsLessThan,
  158.  
  159.     kNumOperators       /* must be last operator            */
  160. } MSG_SearchOperator;
  161.  
  162. /* FEs use this to help build the search dialog box */
  163. typedef enum
  164. {
  165.     widgetText,
  166.     widgetDate,
  167.     widgetMenu,
  168.     widgetInt,        /* added to account for age in days which requires an integer field */
  169.     widgetNone
  170. } MSG_SearchValueWidget;
  171.  
  172. /* Use this to specify the value of a search term */
  173. typedef struct MSG_SearchValue
  174. {
  175.     MSG_SearchAttribute attribute;
  176.     union
  177.     {
  178.         char *string;
  179.         MSG_PRIORITY priority;
  180.         time_t date;
  181.         uint32 msgStatus; /* see MSG_FLAG in msgcom.h */
  182.         uint32 size;
  183.         MessageKey key;
  184.         uint32 age; /* in days */
  185.         MSG_FolderInfo *folder;
  186.     } u;
  187. } MSG_SearchValue;
  188.  
  189. /* Use this to help build menus in the search dialog. See APIs below */
  190. #define kSearchMenuLength 64
  191. typedef struct MSG_SearchMenuItem 
  192. {
  193.     int16 attrib;
  194.     char name[kSearchMenuLength];
  195.     XP_Bool isEnabled;
  196. } MSG_SearchMenuItem;
  197.  
  198. #ifdef XP_CPLUSPLUS
  199.     struct MSG_ScopeTerm;
  200.     struct MSG_ResultElement;
  201.     struct DIR_Server;
  202. #else
  203.     #include "dirprefs.h"
  204.     typedef struct MSG_ScopeTerm MSG_ScopeTerm;
  205.     typedef struct MSG_ResultElement MSG_ResultElement;
  206. #endif
  207.  
  208. XP_BEGIN_PROTOS
  209.  
  210. /* manage lifetime of internal search memory */
  211. MSG_SearchError MSG_SearchAlloc (MSG_Pane *);   /* alloc memory in context  */
  212. MSG_SearchError MSG_SearchFree (MSG_Pane *);    /* free memory in context   */
  213.  
  214. MSG_SearchError MSG_AddSearchTerm (
  215.     MSG_Pane *searchPane,          /* ptr to pane to add criteria            */
  216.     MSG_SearchAttribute attrib,    /* attribute for this term                */
  217.     MSG_SearchOperator op,         /* operator e.g. opContains               */
  218.     MSG_SearchValue *value,        /* value e.g. "Dogbert"                   */
  219.     XP_Bool BooleanAND,            /*  set to true if associated boolean operator is AND */
  220.     char * arbitraryHeader);       /* user defined arbitrary header. ignored unless attrib = attribOtherHeader */
  221.  
  222. /* It's generally not necessary for the FE to read the list of terms after 
  223.  * the list has been built. However, in our Basic/Advanced LDAP search dialogs
  224.  * the FE is supposed to remember the criteria, and since that information is
  225.  * lying around in the backend anyway, we'll just make it available to the FE
  226.  */
  227. MSG_SearchError MSG_CountSearchTerms (
  228.     MSG_Pane *searchPane,
  229.     int *numTerms);
  230. MSG_SearchError MSG_GetNthSearchTerm (
  231.     MSG_Pane *searchPane,
  232.     int whichTerm,
  233.     MSG_SearchAttribute *attrib,
  234.     MSG_SearchOperator *op,
  235.     MSG_SearchValue *value);
  236.  
  237. MSG_SearchError MSG_CountSearchScopes (
  238.     MSG_Pane *searchPane, 
  239.     int *numScopes);
  240. MSG_SearchError MSG_GetNthSearchScope (
  241.     MSG_Pane *searchPane,
  242.     int which,
  243.     MSG_ScopeAttribute *scopeId,
  244.     void **scope);
  245.  
  246. /* add a scope (e.g. a mail folder) to the search */
  247. MSG_SearchError MSG_AddScopeTerm (
  248.     MSG_Pane *searchPane,          /* ptr to pane to add search scope        */
  249.     MSG_ScopeAttribute attrib,     /* what kind of scope term is this        */
  250.     MSG_FolderInfo *folder);       /* which folder to search                 */
  251.  
  252. /* special cases for LDAP since LDAP isn't really a folderInfo */
  253. MSG_SearchError MSG_AddLdapScope (
  254.     MSG_Pane *searchPane,
  255.     DIR_Server *server);
  256. MSG_SearchError MSG_AddAllLdapScopes (
  257.     MSG_Pane *searchPane,
  258.     XP_List *dirServerList);
  259.  
  260. /* Call this function everytime the scope changes! It informs the FE if 
  261.    the current scope support custom header use. FEs should not display the
  262.    custom header dialog if custom headers are not supported */
  263.  
  264. XP_Bool MSG_ScopeUsesCustomHeaders(
  265.     MSG_Master * master,    
  266.     MSG_ScopeAttribute scope,
  267.     void * selection,              /* could be a folder or server based on scope */
  268.     XP_Bool forFilters);           /* is this a filter we are talking about? */
  269.  
  270. XP_Bool MSG_IsStringAttribute(     /* use this to determine if your attribute is a string attrib */
  271.     MSG_SearchAttribute);
  272.  
  273. /* add all scopes of a given type to the search */
  274. MSG_SearchError MSG_AddAllScopes (
  275.     MSG_Pane *searchPane,          /* ptr to pane to add scopes              */
  276.     MSG_Master *master,            /* mail or news scopes                    */
  277.     MSG_ScopeAttribute attrib);    /* what kind of scopes to add             */
  278.  
  279. /* begin execution of the search */
  280. MSG_SearchError MSG_Search (
  281.     MSG_Pane *searchPane);        /* So we know how to work async            */
  282.  
  283. /* manage elements in list of search hits */
  284. MSG_SearchError MSG_GetResultElement (
  285.     MSG_Pane *searchPane,        /* ptr to pane containing results           */
  286.     MSG_ViewIndex idx,           /* zero-based index of result to get        */
  287.     MSG_ResultElement **result); /* filled in resultElement. NOT allocated   */
  288. MSG_SearchError MSG_GetResultAttribute (
  289.     MSG_ResultElement *elem,     /* which result elem to get value for       */
  290.     MSG_SearchAttribute attrib,  /* which attribute to get value for         */
  291.     MSG_SearchValue **result);   /* filled in value                          */
  292. MSG_SearchError MSG_OpenResultElement (
  293.     MSG_ResultElement *elem,     /* which result elem to open                */
  294.     void *window);               /* MSG_Pane* for mail/news, contxt for LDAP */
  295. MWContextType MSG_GetResultElementType (
  296.     MSG_ResultElement *elem);    /* context type needed for this elem        */
  297. MWContext *MSG_IsResultElementOpen (
  298.     MSG_ResultElement *elem);    /* current context if open, NULL if not     */
  299. MSG_SearchError MSG_SortResultList (
  300.     MSG_Pane *searchPane,         /* ptr to pane containing results          */
  301.     MSG_SearchAttribute sortKey,  /* which attribute is the sort key         */
  302.     XP_Bool descending);          /* T- sort descending, F- sort ascending   */
  303. MSG_SearchError MSG_DestroySearchValue (
  304.     MSG_SearchValue *value);      /* free struct and heap-based struct elems */
  305. MSG_SearchError MSG_ModifyLdapResult (
  306.     MSG_ResultElement *elem,      /* which result element to modify          */
  307.     MSG_SearchValue *val);        /* new value to stuff in                   */
  308. MSG_SearchError MSG_AddLdapResultsToAddressBook( 
  309.     MSG_Pane *searchPane,         /* ptr to pane containing results          */
  310.     MSG_ViewIndex *indices,       /* selection array                         */
  311.     int count);                   /* size of array                           */
  312. MSG_SearchError MSG_ComposeFromLdapResults(
  313.     MSG_Pane *searchPane,         /* ptr to pane containing results          */
  314.     MSG_ViewIndex *indices,       /* selection array                         */
  315.     int count);                   /* size of array                           */
  316.  
  317. /* help FEs manage menu selections in Search dialog box */
  318. MSG_SearchError MSG_GetSearchWidgetForAttribute (
  319.     MSG_SearchAttribute attrib,     /* which attr to get UI widget type for  */
  320.     MSG_SearchValueWidget *widget); /* what kind of UI widget specifies attr */
  321.  
  322. /* For referring to DIR_Servers and MSG_FolderInfos polymorphically */
  323. typedef struct MSG_ScopeUnion
  324. {
  325.     MSG_ScopeAttribute *attribute;
  326.     union
  327.     {
  328.         DIR_Server *server;
  329.         MSG_FolderInfo *folder;
  330.     } u;
  331. } MSG_ScopeUnion;
  332.  
  333.  
  334. /* always call this routine b4 calling MSG_GetAttributesForSearchScopes to 
  335.    determine how many elements your MSG_SearchMenuItem array needs to be */
  336. MSG_SearchError MSG_GetNumAttributesForSearchScopes(
  337.     MSG_Master *master, 
  338.     MSG_ScopeAttribute scope,
  339.     void ** selArray,              /* selected items for LCD calculation      */
  340.     uint16 selCount,              /* number of selected items                 */
  341.     uint16 *numItems);              /* out - number of attribute items for scope */
  342.  
  343. MSG_SearchError MSG_GetAttributesForSearchScopes (
  344.     MSG_Master *master,         
  345.     MSG_ScopeAttribute scope,
  346.     void **selArray,              /* selected items for LCD calculation      */
  347.     uint16 selCount,              /* number of selected items                */
  348.     MSG_SearchMenuItem *items,    /* array of caller-allocated structs       */
  349.     uint16 *maxItems);            /* in- max array size; out- num returned   */ 
  350.  
  351. MSG_SearchError MSG_GetOperatorsForSearchScopes (
  352.     MSG_Master *master,         
  353.     MSG_ScopeAttribute scope,
  354.     void **selArray,              /* selected items for LCD calculation      */
  355.     uint16 selCount,              /* number of selected items                */
  356.     MSG_SearchAttribute attrib,   /* return available ops for this attrib    */
  357.     MSG_SearchMenuItem *items,    /* array of caller-allocated structs       */
  358.     uint16 *maxItems);            /* in- max array size; out- num returned   */
  359.  
  360. MSG_SearchError MSG_GetScopeMenuForSearchMessages (
  361.     MSG_Master *master,
  362.     MSG_FolderInfo **selArray,
  363.     uint16 selCount,
  364.     MSG_SearchMenuItem *items,
  365.     uint16 *maxItems);
  366.  
  367. /* always call this routine b4 calling MSG_GetAttributesForFilterScopes to 
  368.    determine how many elements your MSG_SearchMenuItem array needs to be */
  369. MSG_SearchError MSG_GetNumAttributesForFilterScopes(
  370.     MSG_Master *master, 
  371.     MSG_ScopeAttribute scope,      
  372.     void ** selArray,              /* selected items for LCD calculation */
  373.     uint16 selCount,              /* number of selected items            */
  374.     uint16 *numItems);              /* out - number of attribute items for scope */
  375.  
  376. MSG_SearchError MSG_GetAttributesForFilterScopes (
  377.     MSG_Master *master,         
  378.     MSG_ScopeAttribute scope,
  379.     void **selArray,              /* selected items for LCD calculation      */
  380.     uint16 selCount,              /* number of selected items                */
  381.     MSG_SearchMenuItem *items,    /* array of caller-allocated structs       */
  382.     uint16 *maxItems);            /* in- max array size; out- num returned   */ 
  383.  
  384. MSG_SearchError MSG_GetOperatorsForFilterScopes (
  385.     MSG_Master *master,         
  386.     MSG_ScopeAttribute scope,
  387.     void **selArray,              /* selected items for LCD calculation      */
  388.     uint16 selCount,              /* number of selected items                */
  389.     MSG_SearchAttribute attrib,   /* return available ops for this attrib    */
  390.     MSG_SearchMenuItem *items,    /* array of caller-allocated structs       */
  391.     uint16 *maxItems);            /* in- max array size; out- num returned   */
  392.  
  393. /*****************************************************************************
  394.  These two functions have been added to the search APIs to help support Arbitrary
  395.  Headers. In particular, the FEs need to be able to grab a semaphore when they
  396.  create an edit headers dialog (we only want to allow 1 dialog to be open at a time).
  397.  AcquireEditHeadersSemaphore returns TRUE if the FE successfully acquired the semaphore
  398.  and FALSE if someone else acquired it. ReleaseEditHeaderSemaphore returns TRUE if you
  399.  were the original holder of the semaphore and the semaphore was released. FALSE if you
  400.  were not the original holder 
  401.  **********************************************************************************/
  402. XP_Bool MSG_AcquireEditHeadersSemaphore (MSG_Master * master, void * holder);
  403. XP_Bool MSG_ReleaseEditHeadersSemaphore  (MSG_Master * master, void * holder);
  404.  
  405. MSG_SearchError MSG_SearchAttribToDirAttrib (
  406.     MSG_SearchAttribute searchAttrib,
  407.     DIR_AttributeId *dirAttrib);
  408.  
  409.  
  410. MSG_SearchError MSG_GetBasicLdapSearchAttributes (
  411.     DIR_Server *server, 
  412.     MSG_SearchMenuItem *items, 
  413.     int *maxItems);
  414.  
  415. /* maybe these belong in msgcom.h? */
  416. void MSG_GetPriorityName (MSG_PRIORITY priority, char *name, uint16 max);
  417. void MSG_GetUntranslatedPriorityName (MSG_PRIORITY priority, 
  418.                                                                             char *name, uint16 max);
  419. void MSG_GetStatusName (uint32 status, char *name, uint16 max);
  420. MSG_PRIORITY MSG_GetPriorityFromString(const char *priority);
  421.  
  422. /* support for profile searching in Dredd */
  423. MSG_SearchError MSG_SaveProfileStatus (MSG_Pane *searchPane, XP_Bool *enabled);
  424. MSG_SearchError MSG_SaveProfile (MSG_Pane *searchPane, const char *profileName);
  425.  
  426. /* support for searching all Dredd groups + all subscribed groups */
  427. MSG_SearchError MSG_AddAllSearchableGroupsStatus(MSG_Pane *searchPane, XP_Bool *enabled);
  428.  
  429. /* support for opening a search result in its thread pane context */
  430. XP_Bool MSG_GoToFolderStatus (MSG_Pane *searchPane, 
  431.                               MSG_ViewIndex *indices,
  432.                               int32 numIndices);
  433.  
  434. /* used between libnet and libmsg to allow searching for characters which
  435.  * are otherwise significant in news: URLs
  436.  */
  437. extern char *MSG_EscapeSearchUrl (const char *value);
  438. extern char *MSG_UnEscapeSearchUrl (const char *value);
  439.  
  440. /* This is how "search:" of different mail/news folder types works */
  441. extern int MSG_ProcessSearch (MWContext *context);
  442. extern int MSG_InterruptSearch (MWContext *context);
  443.  
  444.  
  445. XP_END_PROTOS
  446.  
  447. #endif /* _MSG_SRCH_H */
  448.