home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / include / msg_filt.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  9.2 KB  |  220 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. /* foobar Public API for mail (and news?) filters */
  19. #ifndef MSG_RULE_H
  20. #define MSG_RULE_H
  21.  
  22. /*
  23.     Terminology -    Filter - either a Rule (defined with GUI) or a (Java) Script
  24.                     Rule - 
  25. */
  26. #include "msg_srch.h"
  27.  
  28. typedef enum
  29. {
  30.     FilterError_Success = 0,    /* no error */
  31.     FilterError_First = SearchError_Last + 1,        /* no functions return this; just for bookkeeping */
  32.     FilterError_NotImplemented,    /* coming soon */
  33.     FilterError_OutOfMemory,    /* out of memory */
  34.     FilterError_FileError,        /* error reading or writing the rules file */
  35.     FilterError_InvalidVersion, /* invalid filter file version */
  36.     FilterError_InvalidIndex,   /* Invalid filter index */
  37.     FilterError_InvalidMotion,  /* invalid filter move motion */
  38.     FilterError_InvalidFilterType, /* method doesn't accept this filter type */
  39.     FilterError_NullPointer,    /* a required pointer parameter was null */
  40.     FilterError_NotRule,        /* tried to get rule for non-rule filter */
  41.     FilterError_NotScript,        /* tried to get a script name for a non-script filter */
  42.     FilterError_InvalidAction,    /* invalid action */
  43.     FilterError_SearchError,    /* error in search code */
  44.     FilterError_Last        /* no functions return this; just for bookkeeping */
  45. } MSG_FilterError;
  46.  
  47.  
  48. typedef enum
  49.  {
  50.      acNone,                /* uninitialized state */
  51.          acMoveToFolder,
  52.          acChangePriority,
  53.          acDelete,
  54.          acMarkRead,
  55.          acKillThread,
  56.      acWatchThread
  57.  } MSG_RuleActionType;
  58.  
  59. typedef enum 
  60. {
  61.     filterInboxRule = 0x1,
  62.     filterInboxJavaScript = 0x2,
  63.     filterInbox = 0x3,
  64.     filterNewsRule = 0x4,
  65.     filterNewsJavaScript = 0x8,
  66.     filterNews=0xb,
  67.     filterAll=0xf
  68. } MSG_FilterType;
  69.  
  70. typedef enum
  71. {
  72.     filterUp,
  73.     filterDown
  74. } MSG_FilterMotion;
  75.  
  76. typedef int32 MSG_FilterIndex;
  77.  
  78. /* opaque struct defs - defined in libmsg/pmsgfilt.h */
  79. #ifdef XP_CPLUSPLUS
  80.     struct MSG_Filter;
  81.     struct MSG_Rule;
  82.     struct MSG_RuleAction;
  83.     struct MSG_FilterList;
  84. #else
  85.     typedef struct MSG_FilterList MSG_FilterList;
  86.     typedef struct MSG_Filter MSG_Filter;
  87.     typedef struct MSG_Rule MSG_Rule;
  88.     typedef struct MSG_RuleAction MSG_RuleAction;
  89. #endif
  90.  
  91. XP_BEGIN_PROTOS
  92.  
  93. /* Front ends call MSG_OpenFilterList to get a handle to a FilterList, of existing MSG_Filter *.
  94.     These are manipulated by the front ends as a result of user interaction
  95.    with dialog boxes. To apply the new list, fe's call MSG_CloseFilterList.
  96.  
  97.    For example, if the user brings up the rule management UI, deletes a rule,
  98.    and presses OK, the front end calls MSG_RemoveFilterListAt, and
  99.    then MSG_CloseFilterList.
  100.  
  101. */
  102. MSG_FilterError MSG_OpenFilterList(MSG_Master *master, MSG_FilterType type, MSG_FilterList **filterList);
  103. MSG_FilterError MSG_OpenFolderFilterList(MSG_Pane *pane, MSG_FolderInfo *folder, MSG_FilterType type, MSG_FilterList **filterList);
  104. MSG_FilterError MSG_CloseFilterList(MSG_FilterList *filterList);
  105. MSG_FilterError    MSG_SaveFilterList(MSG_FilterList *filterList);    /* save without deleting */
  106. MSG_FilterError MSG_CancelFilterList(MSG_FilterList *filterList);
  107.  
  108. MSG_FolderInfo *MSG_GetFolderInfoForFilterList(MSG_FilterList *filterList);
  109. MSG_FilterError MSG_GetFilterCount(MSG_FilterList *filterList, int32 *pCount);
  110. MSG_FilterError MSG_GetFilterAt(MSG_FilterList *filterList, 
  111.                             MSG_FilterIndex filterIndex, MSG_Filter **filter);
  112. /* these methods don't delete filters - they just change the list. FE still must
  113.     call MSG_DestroyFilter to delete a filter.
  114. */
  115. MSG_FilterError MSG_SetFilterAt(MSG_FilterList *filterList, 
  116.                             MSG_FilterIndex filterIndex, MSG_Filter *filter);
  117. MSG_FilterError MSG_RemoveFilterAt(MSG_FilterList *filterList,
  118.                             MSG_FilterIndex filterIndex);
  119. MSG_FilterError MSG_MoveFilterAt(MSG_FilterList *filterList, 
  120.                             MSG_FilterIndex filterIndex, MSG_FilterMotion motion);
  121. MSG_FilterError MSG_InsertFilterAt(MSG_FilterList *filterList, 
  122.                             MSG_FilterIndex filterIndex, MSG_Filter *filter);
  123.  
  124. MSG_FilterError MSG_EnableLogging(MSG_FilterList *filterList, XP_Bool enable);
  125. XP_Bool            MSG_IsLoggingEnabled(MSG_FilterList *filterList);
  126.  
  127. /* In general, any data gotten with MSG_*Get is good until the owning object
  128.    is deleted, or the data is replaced with a MSG_*Set call. For example, the name
  129.    returned in MSG_GetFilterName is valid until either the filter is destroyed,
  130.    or MSG_SetFilterName is called on the same filter.
  131.  */
  132. MSG_FilterError MSG_CreateFilter (MSG_FilterType type,    char *name,    MSG_Filter **result);            
  133. MSG_FilterError MSG_DestroyFilter(MSG_Filter *filter);
  134. MSG_FilterError MSG_GetFilterType(MSG_Filter *, MSG_FilterType *filterType);
  135. MSG_FilterError MSG_EnableFilter(MSG_Filter *, XP_Bool enable);
  136. MSG_FilterError MSG_IsFilterEnabled(MSG_Filter *, XP_Bool *enabled);
  137. MSG_FilterError MSG_GetFilterRule(MSG_Filter *, MSG_Rule ** result);
  138. MSG_FilterError MSG_GetFilterName(MSG_Filter *, char **name);    
  139. MSG_FilterError MSG_SetFilterName(MSG_Filter *, const char *name);
  140. MSG_FilterError MSG_GetFilterDesc(MSG_Filter *, char **description);
  141. MSG_FilterError MSG_SetFilterDesc(MSG_Filter*, const char *description);
  142. MSG_FilterError MSG_GetFilterScript(MSG_Filter *, char **name);
  143. MSG_FilterError MSG_SetFilterScript(MSG_Filter *, const char *name);
  144.  
  145. MSG_FilterError MSG_RuleAddTerm(MSG_Rule *,     
  146.     MSG_SearchAttribute attrib,    /* attribute for this term                */
  147.     MSG_SearchOperator op,         /* operator e.g. opContains               */
  148.     MSG_SearchValue *value,        /* value e.g. "Dogbert"                   */
  149.     XP_Bool BooleanAND,            /* TRUE if AND is the boolean operator. FALSE if OR is the boolean operators */
  150.     char * arbitraryHeader);       /* arbitrary header specified by user. ignored unless attrib = attribOtherHeader */
  151.  
  152. MSG_FilterError MSG_RuleGetNumTerms(MSG_Rule *, int32 *numTerms);
  153.  
  154. MSG_FilterError MSG_RuleGetTerm(MSG_Rule *, int32 termIndex, 
  155.     MSG_SearchAttribute *attrib,    /* attribute for this term                */
  156.     MSG_SearchOperator *op,         /* operator e.g. opContains               */
  157.     MSG_SearchValue *value,         /* value e.g. "Dogbert"                   */
  158.     XP_Bool *BooleanAnd,                /* TRUE if AND is the boolean operator. FALSE if OR is the boolean operator */
  159.     char ** arbitraryHeader);        /* arbitrary header specified by user. ignore unless attrib = attribOtherHeader */
  160.  
  161. MSG_FilterError MSG_RuleSetScope(MSG_Rule *, MSG_ScopeTerm *scope);
  162. MSG_FilterError MSG_RuleGetScope(MSG_Rule *, MSG_ScopeTerm **scope);
  163.  
  164. /* if type is acChangePriority, value is a pointer to priority.
  165.    If type is acMoveToFolder, value is pointer to folder name.
  166.    Otherwise, value is ignored.
  167. */
  168. MSG_FilterError MSG_RuleSetAction(MSG_Rule *, MSG_RuleActionType type, void *value);
  169. MSG_FilterError MSG_RuleGetAction(MSG_Rule *, MSG_RuleActionType *type, void **value);
  170.  
  171. /* help FEs manage menu choices in Filter dialog box */
  172.  
  173. /* Use this to help build menus in the filter dialogs. See APIs below */
  174. typedef struct MSG_RuleMenuItem 
  175. {
  176.     int16 attrib;
  177.     char name[32];
  178. } MSG_RuleMenuItem;
  179.  
  180.  
  181. MSG_FilterError MSG_GetRuleActionMenuItems (
  182.     MSG_FilterType type,        /* type of filter                          */
  183.     MSG_RuleMenuItem *items,    /* array of caller-allocated structs       */
  184.     uint16 *maxItems);            /* in- max array size; out- num returned   */ 
  185.  
  186. MSG_FilterError MSG_GetFilterWidgetForAction( MSG_RuleActionType action,
  187.                                               MSG_SearchValueWidget *widget );
  188.  
  189. MSG_SearchError MSG_GetValuesForAction( MSG_RuleActionType action,
  190.                                                MSG_SearchMenuItem *items, 
  191.                                                uint16 *maxItems);
  192.  
  193. void            MSG_ViewFilterLog(MSG_Pane *pane);
  194.  
  195. /*
  196. ** Adding/editting javascript filters.
  197. **
  198. ** The FE calls one of the below functions, along with a callback and some closure
  199. ** data.  This callback is invoked when the user clicks OK in the JS filter dialog.
  200. ** If CANCEL is pressed, the callback is not invoked.
  201. **
  202. ** If the user called MSG_EditJSFilter, the filter_index parameter of the callback
  203. ** is the same one passed in.  If the user called MSG_NewJSFilter, the filter_index
  204. ** parameter is -1.
  205. **
  206. ** The filter_changed parameter is TRUE if the user modified any of the fields of
  207. ** the javascript filter, and FALSE otherwise.
  208. */
  209. typedef void (*JSFilterCallback)(void* arg, MSG_FilterIndex filter_index, XP_Bool filter_changed);
  210.  
  211. void MSG_EditJSFilter(MWContext *context, MSG_FilterList *filter_list,
  212.                       MSG_FilterIndex filter_index,
  213.                       JSFilterCallback cb, void *arg);
  214. void MSG_NewJSFilter(MWContext *context, MSG_FilterList *filter_list,
  215.                      MSG_FilterType filter_type, JSFilterCallback cb, void *arg);
  216.  
  217. XP_END_PROTOS
  218.  
  219. #endif
  220.