offapi/com/sun/star/ucb/ContentAction.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: ContentAction.idl,v $
  10  * $Revision: 1.8 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ucb_ContentAction_idl__
  31 #define __com_sun_star_ucb_ContentAction_idl__
  32
  33
  34 //=============================================================================
  35
  36 module com { module sun { module star { module ucb {
  37
  38 //=============================================================================
  39 /** specifies actions which can be transported with content events.
  40
  41     <p>
  42     The situations under which contents will send ContentEvents of the various
  43     action types are described below.  The description is broken into a list of
  44     useful definitions, a list of events that happen to contents, and a list of
  45     reactions taken by contents in response to those events.
  46     </p>
  47
  48     <p>
  49     The definitions are as follows:
  50     </p>
  51
  52     <table border =1>
  53     <tr><td>D1</td><td>A content C has an identifier id(C).</td></tr>
  54     <tr><td>D2</td><td>A content C is in one of two states, Alive or Deleted.
  55                        </td></tr>
  56     <tr><td>D3</td><td>A folder content F has a set of children H(F) that is a
  57                        set of content identifiers. For example, an "open"
  58                        command will usualy return a     subset of the contents
  59                        denoted by H(F).</td></tr>
  60     </table>
  61
  62     <p>
  63     The events that can happen to contents (and that are of interest in this
  64     context) are listed next.  Note that 'event' here does not mean an
  65     ContentEvent, but rather some event that occurs either because some content
  66     processes a command, or because a content gets informed about a relevant
  67     change in the underlying system it represents.
  68     </p>
  69
  70     <table border =1>
  71     <tr><td>E1</td><td>The identifier of a content C changes from id1(C) == A
  72                        to id2(C) == B, denoted as E1(C: A->B). For example,
  73                        this event may occur when content C processes a
  74                        "setPropertyValues" command changing its "Title" propery,
  75                        or when afolder that hierarchicaly contains C changes
  76                        its identity.</td></tr>
  77     <tr><td>E2</td><td>The state of a content C changes from Alive to Deleted,
  78                        denoted as E2(C). For example, this event may occur when
  79                        content C processes a "delete"   command, or when a content
  80                        representing an IMAP message gets informed       by the IMAP
  81                        server that the message has been deleted.</td></tr>
  82     <tr><td>E3</td><td>The set of children of a folder content F is enlarged by
  83                        some identifier A (that was not previously in that set,
  84                        i.e., !(A in H1(F)) && (A in H2(F))), denoted as E3(F, A).
  85                        For example, this event may occur when a new content
  86                        created at folder F processes its "insert" command, or
  87                        when a folder representing       an IMAP mailbox gets informed
  88                        by the IMAP server that a new message has arrived at that
  89                        mailbox.</td></tr>
  90     </table>
  91
  92     <p>
  93     Finally, the list of reactions taken by contents in response to the above
  94     events gives a description of what kinds of ContentEvents are sent in which
  95     situations:
  96     </p>
  97
  98     <table border =1>
  99     <tr><td>R1</td><td>E1(C: A->B) results in C sending an EXCHANGED
 100                        ContentEvent, which then results in the following: All
 101                        folders F that used to have A as a child, but will not
 102                        have B as a child, i.e., (A in H1(F)) && !(B in H2(F)),
 103                        send a REMOVED ContentEvent.</td></tr>
 104     <tr><td>R2</td><td>E2(C) results in C sending a DELETED ContentEvent,
 105                        which then results in the following:  All folders F that
 106                        used to have A as a child, but will not continue to have
 107                        A as a child, i.e., (A in H1(F)) && !(A in H2(F)), send
 108                        a REMOVED event.</td></tr>
 109     <tr><td>R3</td><td>E3(F, A) results in F sending an INSERTED event.</td></tr>
 110     </table>
 111 */
 112 published constants ContentAction
 113 {
 114     //-------------------------------------------------------------------------
 115     /** A content was inserted into a folder content (i.e., while updating the
 116         folder).
 117
 118         <p>This action must be notified at the listeners of the folder content.
 119     */
 120     const long INSERTED = 0;
 121
 122     //-------------------------------------------------------------------------
 123     /** A content was removed from a folder content, but not physically
 124         destroyed (i.e., due to rules just applied to the folder).
 125
 126         <p>This action must be notified at the listeners of the folder content.
 127     */
 128     const long REMOVED = 1;
 129
 130     //-------------------------------------------------------------------------
 131     /** A content was physically destroyed.
 132
 133         <p>Events containing this action may be generated at any time. So a
 134         content event listener should be prepared to get notified the "death"
 135         of the related content!
 136
 137         <p>This action must be notified at the listeners of the deleted
 138         content.
 139     */
 140     const long DELETED = 2;
 141
 142     //-------------------------------------------------------------------------
 143     /** This Action indicates that a content has changed its identity (i.e.
 144         after renaming a file system folder).
 145
 146         <p>This action must be notified at the listeners of the exchanged
 147         content.
 148     */
 149     const long EXCHANGED = 4;
 150
 151     //-------------------------------------------------------------------------
 152     /** This is obsolete and should no longer be used.
 153
 154         @deprecated
 155     */
 156     const long SEARCH_MATCHED = 128;
 157
 158 };
 159
 160 //=============================================================================
 161
 162 }; }; }; };
 163
 164 #endif