1 /*

     2 * Copyright (c) 2006, 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Interface for managing cached presentity group information.

    15 *

    16 */

    17 

    18 #ifndef MPROTOCOLPRESENTITYGROUPSDATAHOST_H

    19 #define MPROTOCOLPRESENTITYGROUPSDATAHOST_H

    20 

    21 

    22 #include <e32base.h>

    23 #include <presenceprotocolpluginhostifids.hrh>

    24 #include <ximpbase.h>

    25 

    26 

    27 class MXIMPIdentity;

    28 class MXIMPObjectCollection;

    29 class MPresentityGroupInfo;

    30 class MPresentityGroupMemberInfo;

    31 class MXIMPDataSubscriptionState;

    32 class MXIMPStatus;

    33 

    34 

    35 

    36 /**

    37  * Interface for managing cached presentity group information.

    38  *

    39  * Interface used by protocol adaptations to manage

    40  * manage presentity group information and presentity

    41  * group member information in XIMP Framework

    42  * internal data cache.

    43  *

    44  * This interface is implemented by XIMP Framework.

    45  * Protocol adaptation can obtain reference to this

    46  * interface from MXIMPProtocolConnectionHost interface.

    47  *

    48  * For each separated protocol connection, protocol

    49  * adaptation must use the specific

    50  * MProtocolPresentityGroupsDataHost instance,

    51  * what is received from the connection specific

    52  * MXIMPProtocolConnectionHost instance.

    53  *

    54  * @ingroup ximppresprotocolpluginhostapi

    55  * @since S60 v3.2

    56  */

    57 class MProtocolPresentityGroupsDataHost : public MXIMPBase

    58     {

    59 public:

    60 

    61     /** Interface ID for the MProtocolPresentityGroupsDataHost. */

    62     enum { KInterfaceId = PRES_IF_ID_PROTOCOL_PRESENTITY_GROUPS_DATAHOST };

    63 

    64 protected:

    65 

    66     /**

    67      * Protected destructor. Object instancies

    68      * can't be deleted via this interface.

    69      */

    70     virtual ~MProtocolPresentityGroupsDataHost() {}

    71 

    72 

    73 

    74 public: // Handling presentity group information

    75 

    76 

    77     /**

    78      * Notifies XIMP Framework from

    79      * presentity group list contents.

    80      *

    81      * Protocol adaptation implementation can call this

    82      * method to notify XIMP Framework from

    83      * complete presentity group list content.

    84      * XIMP Framework calculates the changes

    85      * (new and removed presentity groups) compared to previous

    86      * presence presentity group list content, and notifies

    87      * the subscribing clients from data changes.

    88      *

    89      * XIMP Framework takes ownership of the object

    90      * collection and all objects contained within, if

    91      * the method succeeds without a leave.

    92      *

    93      *

    94      * @param [in] aGroupList

    95      *        MXIMPObjectCollection object containing zero or

    96      *        more MPresentityGroupInfo objects. Each

    97      *        contained MPresentityGroupInfo shall present

    98      *        single presentity group within the presentity

    99      *        group list.

   100      *

   101      * @return The request ID identifying the issued request.

   102      *         Data cache request is processed asynchronously and

   103      *         its completion is signalled to adaptation direction

   104      *         through MXIMPProtocolConnectionHostObserver interface,

   105      *         with MXIMPProtocolRequestCompleteEvent event.

   106      *

   107      * @leave KErrNoMemory if failed to allocate memory.

   108      * @leave KErrArgument if NULL argument(s) were provided.

   109      */

   110     virtual TXIMPRequestId HandlePresentityGroupListL(

   111                 MXIMPObjectCollection* aGroupList ) = 0;

   112 

   113 

   114 

   115     /**

   116      * Notifies XIMP Framework from new

   117      * presentity group list entry.

   118      *

   119      * Protocol adaptation implementation can call this

   120      * method to notify XIMP Framework from

   121      * new presentity group list entry. XIMP Framework

   122      * calculates the change, from previous presentity

   123      * group list content, and notifies the subscribing

   124      * clients from data changes.

   125      *

   126      * XIMP Framework takes ownership of the argument(s),

   127      * if method succeeds without a leave.

   128      *

   129      * @param [in] aGroupInfo

   130      *        MPresentityGroupInfo object holding

   131      *        information about new presentity group entry.

   132      *        New presentity group is added to the presentity

   133      *        group list.

   134      *

   135      * @return The request ID identifying the issued request.

   136      *         Data cache request is processed asynchronously and

   137      *         its completion is signalled to adaptation direction

   138      *         through MXIMPProtocolConnectionHostObserver interface,

   139      *         with MXIMPProtocolRequestCompleteEvent event.

   140      *

   141      * @leave KErrNoMemory if failed to allocate memory.

   142      * @leave KErrArgument if NULL argument(s) were provided.

   143      */

   144     virtual TXIMPRequestId HandlePresentityGroupCreatedL(

   145                 MPresentityGroupInfo* aGroupInfo ) = 0;

   146 

   147 

   148 

   149     /**

   150      * Notifies XIMP Framework from deletion of

   151      * existing presentity group.

   152      *

   153      * Protocol adaptation implementation can call this

   154      * method to notify XIMP Framework from deletion

   155      * of existing presentity group. XIMP Framework

   156      * calculates the change, from previous presentity group

   157      * list content, and notifies the subscribing clients

   158      * from data changes.

   159      *

   160      * XIMP Framework takes ownership of the argument(s),

   161      * if method succeeds without a leave.

   162      *

   163      * @param [in] aGroupId

   164      *        MXIMPIdentity object identifying the

   165      *        presentity group which were deleted and thus

   166      *        needs to be removed from presentity group list.

   167      *

   168      * @return The request ID identifying the issued request.

   169      *         Data cache request is processed asynchronously and

   170      *         its completion is signalled to adaptation direction

   171      *         through MXIMPProtocolConnectionHostObserver interface,

   172      *         with MXIMPProtocolRequestCompleteEvent event.

   173      *

   174      * @leave KErrNoMemory if failed to allocate memory.

   175      * @leave KErrArgument if NULL argument(s) were provided.

   176      */

   177     virtual TXIMPRequestId HandlePresentityGroupDeletedL(

   178                 MXIMPIdentity* aGroupId ) = 0;

   179 

   180 

   181 

   182     /**

   183      * Notifies XIMP Framework from update of

   184      * existing presentity group displayname.

   185      *

   186      * Protocol adaptation implementation can call this

   187      * method to notify XIMP Framework from update

   188      * of existing presentity group displayname. XIMP Framework

   189      * calculates the change, from previous presentity group

   190      * list content, and notifies the subscribing clients

   191      * from data changes.

   192      *

   193      * XIMP Framework takes ownership of the argument(s),

   194      * if method succeeds without a leave.

   195      *

   196      * @param [in] aGroupInfo

   197      *        MPresentityGroupInfo object identifying the

   198      *        presentity group and new displayname for the group.

   199      *

   200      * @return The request ID identifying the issued request.

   201      *         Data cache request is processed asynchronously and

   202      *         its completion is signalled to adaptation direction

   203      *         through MXIMPProtocolConnectionHostObserver interface,

   204      *         with MXIMPProtocolRequestCompleteEvent event.

   205      *

   206      * @leave KErrNoMemory if failed to allocate memory.

   207      * @leave KErrArgument if NULL argument(s) were provided.

   208      */

   209     virtual TXIMPRequestId HandlePresentityGroupDisplayNameUpdatedL(

   210                 MPresentityGroupInfo* aGroupInfo ) = 0;

   211 

   212 

   213 

   214     /**

   215      * Gets data subscription state for presentity group list.

   216      *

   217      * Protocol adaptation can call this method to retrieve

   218      * presentity group lists data subscription state.

   219      * Protocol adaptation can use data subscription state

   220      * information, to optimize its own processing and

   221      * network trafic amount.

   222      *

   223      * @return Presentity group list data subscription state.

   224      *         Interface ownership is not returned to caller.

   225      *         Caller shouldn't cache the returned reference

   226      *         for later use.

   227      */

   228     virtual const MXIMPDataSubscriptionState&

   229                 PresentityGroupListDataSubscriptionState() const = 0;

   230 

   231 

   232 

   233     /**

   234      * Updates data subscription state for presentity group list.

   235      *

   236      * Updates data subscription state for presentity group list.

   237      * XIMP Framework calculates the subscription state change,

   238      * from previous presentity group list, and

   239      * notifies the subscribing clients from data changes.

   240      *

   241      * XIMP Framework takes ownership of the argument(s),

   242      * if method succeeds without a leave.

   243      *

   244      * @param [in] aSubscriptionState

   245      *        New data subscription state for presentity group list.

   246      *

   247      * @param [in] aStatus

   248      *        Optional status object describing the

   249      *        the reason, why protocol adaptation updated

   250      *        data item subscription state. Given status object

   251      *        is passed to clients through data item specific

   252      *        data change event. NULL value is accepted.

   253      *

   254      * @return The request ID identifying the issued request.

   255      *         Data cache request is processed asynchronously and

   256      *         its completion is signalled to adaptation direction

   257      *         through MXIMPProtocolConnectionHostObserver interface,

   258      *         with MXIMPProtocolRequestCompleteEvent event.

   259      *

   260      * @leave KErrNoMemory if failed to allocate memory.

   261      * @leave KErrArgument if NULL subscription state argument was provided.

   262      */

   263     virtual TXIMPRequestId SetPresentityGroupListDataSubscriptionStateL(

   264                 MXIMPDataSubscriptionState* aSubscriptionState,

   265                 MXIMPStatus* aStatus ) = 0;

   266 

   267 

   268 

   269 public: // Handling presentity group content

   270 

   271 

   272     /**

   273      * Notifies XIMP Framework from

   274      * presentity group contents.

   275      *

   276      * Protocol adaptation implementation can call this

   277      * method to notify XIMP Framework from presentity group

   278      * content. XIMP Framework calculates the changes

   279      * (added and removed group members) compared to previous

   280      * presentity group content, and notifies the subscribing

   281      * clients from data changes.

   282      *

   283      * XIMP Framework takes ownership of the object

   284      * collection and all objects contained within, if

   285      * the method succeeds without a leave.

   286      *

   287      * @param [in] aGroupId

   288      *        MXIMPIdentity object identifying the presentity group

   289      *        of which content is notified here.

   290      *

   291      * @param [in] aGroupMembers

   292      *        MXIMPObjectCollection object containing zero or

   293      *        more MPresentityGroupMemberInfo objects. Each

   294      *        contained MPresentityGroupMemberInfo shall

   295      *        present single presentity group member, within

   296      *        the presentity group.

   297      *

   298      * @return The request ID identifying the issued request.

   299      *         Data cache request is processed asynchronously and

   300      *         its completion is signalled to adaptation direction

   301      *         through MXIMPProtocolConnectionHostObserver interface,

   302      *         with MXIMPProtocolRequestCompleteEvent event.

   303      *

   304      * @leave KErrNoMemory if failed to allocate memory.

   305      * @leave KErrArgument if NULL argument(s) were provided.

   306      */

   307     virtual TXIMPRequestId HandlePresentityGroupContentL(

   308                 MXIMPIdentity* aGroupId,

   309                 MXIMPObjectCollection* aGroupMembers ) = 0;

   310 

   311 

   312 

   313     /**

   314      * Notifies XIMP Framework from new

   315      * presentity group member entry.

   316      *

   317      * Protocol adaptation implementation can call this

   318      * method to notify XIMP Framework from

   319      * new presentity group member entry. XIMP Framework

   320      * calculates the change, from previous presentity

   321      * group content, and notifies the subscribing

   322      * clients from data changes.

   323      *

   324      * XIMP Framework takes ownership of the argument(s),

   325      * if method succeeds without a leave.

   326      *

   327      * @param [in] aGroupId

   328      *        MXIMPIdentity object identifying the presentity

   329      *        group to where the group member is added.

   330      *

   331      * @param [in] aGroupMember

   332      *        MPresentityGroupMemberInfo object holding

   333      *        information about new presentity group member

   334      *        entry. New presentity group member is added

   335      *        to the presentity group content.

   336      *

   337      * @return The request ID identifying the issued request.

   338      *         Data cache request is processed asynchronously and

   339      *         its completion is signalled to adaptation direction

   340      *         through MXIMPProtocolConnectionHostObserver interface,

   341      *         with MXIMPProtocolRequestCompleteEvent event.

   342      *

   343      * @leave KErrNoMemory if failed to allocate memory.

   344      * @leave KErrArgument if NULL argument(s) were provided.

   345      */

   346     virtual TXIMPRequestId HandlePresentityGroupMemberAddedL(

   347                 MXIMPIdentity* aGroupId,

   348                 MPresentityGroupMemberInfo* aGroupMember ) = 0;

   349 

   350 

   351 

   352     /**

   353      * Notifies XIMP Framework from remove of

   354      * existing presentity group member.

   355      *

   356      * Protocol adaptation implementation can call this

   357      * method to notify XIMP Framework from remove

   358      * of existing presentity group member. XIMP Framework

   359      * calculates the change, from previous presentity group

   360      * content, and notifies the subscribing clients

   361      * from data changes.

   362      *

   363      * XIMP Framework takes ownership of the argument(s),

   364      * if method succeeds without a leave.

   365      *

   366      * @param [in] aGroupId

   367      *        MXIMPIdentity object identifying the presentity

   368      *        group from where to remove the group member.

   369      *

   370      * @param [in] aGroupMemberId

   371      *        MXIMPIdentity object identifying the presentity

   372      *        group member which to remove from the presentity

   373      *        group.

   374      *

   375      * @return The request ID identifying the issued request.

   376      *         Data cache request is processed asynchronously and

   377      *         its completion is signalled to adaptation direction

   378      *         through MXIMPProtocolConnectionHostObserver interface,

   379      *         with MXIMPProtocolRequestCompleteEvent event.

   380      *

   381      * @leave KErrNoMemory if failed to allocate memory.

   382      * @leave KErrArgument if NULL argument(s) were provided.

   383      */

   384     virtual TXIMPRequestId HandlePresentityGroupMemberRemovedL(

   385                 MXIMPIdentity* aGroupId,

   386                 MXIMPIdentity* aGroupMemberId ) = 0;

   387 

   388 

   389 

   390     /**

   391      * Notifies XIMP Framework from displayname update of

   392      * existing presentity group member.

   393      *

   394      * Protocol adaptation implementation can call this

   395      * method to notify XIMP Framework from displayname

   396      * update of existing presentity group member.

   397      * XIMP Framework calculates the change, from previous

   398      * presentity group content, and notifies the subscribing

   399      * clients from data changes.

   400      *

   401      * XIMP Framework takes ownership of the argument(s),

   402      * if method succeeds without a leave.

   403      *

   404      * @param [in] aGroupId

   405      *        MXIMPIdentity object identifying the presentity

   406      *        group which member displayname to update.

   407      *

   408      * @param [in] aGroupMember

   409      *        MPresentityGroupMemberInfo object identifying

   410      *        the presentity group member and its new displayname.

   411      *

   412      * @return The request ID identifying the issued request.

   413      *         Data cache request is processed asynchronously and

   414      *         its completion is signalled to adaptation direction

   415      *         through MXIMPProtocolConnectionHostObserver interface,

   416      *         with MXIMPProtocolRequestCompleteEvent event.

   417      *

   418      * @leave KErrNoMemory if failed to allocate memory.

   419      * @leave KErrArgument if NULL argument(s) were provided.

   420      */

   421     virtual TXIMPRequestId HandlePresentityGroupMemberDisplayNameUpdatedL(

   422                 MXIMPIdentity* aGroupId,

   423                 MPresentityGroupMemberInfo* aGroupMember ) = 0;

   424 

   425 

   426 

   427     /**

   428      * Gets data subscription state for presentity group.

   429      *

   430      * Protocol adaptation can call this method to retrieve

   431      * given presentity groups content subscription state.

   432      * Protocol adaptation can use data subscription state

   433      * information, to optimize its own processing and

   434      * network trafic amount.

   435      *

   436      * @return Presentity groups content subscription state.

   437      *         Interface ownership is not returned to caller.

   438      *         Caller shouldn't cache the returned reference

   439      *         for later use.

   440      */

   441     virtual const MXIMPDataSubscriptionState&

   442                 PresentityGroupContentDataSubscriptionState(

   443                 const MXIMPIdentity& aGroupId ) const = 0;

   444 

   445 

   446 

   447     /**

   448      * Updates data subscription state for

   449      * presentity group content.

   450      *

   451      * Updates data subscription state for presentity group content.

   452      * XIMP Framework calculates the subscription state change,

   453      * from previous presentity group content, and

   454      * notifies the subscribing clients from data changes.

   455      *

   456      * XIMP Framework takes ownership of the argument(s),

   457      * if method succeeds without a leave.

   458      *

   459      * @param [in] aGroupId

   460      *        MXIMPIdentity object identifying the presentity

   461      *        group of which data subscription state is

   462      *        updated here.

   463      *

   464      * @param [in] aSubscriptionState

   465      *        New data subscription state for presentity group .

   466      *

   467      * @param [in] aStatus

   468      *        Optional status object describing the

   469      *        the reason, why protocol adaptation updated

   470      *        data item subscription state. Given status object

   471      *        is passed to clients through data item specific

   472      *        data change event. NULL value is accepted.

   473      *

   474      * @return The request ID identifying the issued request.

   475      *         Data cache request is processed asynchronously and

   476      *         its completion is signalled to adaptation direction

   477      *         through MXIMPProtocolConnectionHostObserver interface,

   478      *         with MXIMPProtocolRequestCompleteEvent event.

   479      *

   480      * @leave KErrNoMemory if failed to allocate memory.

   481      * @leave KErrArgument if NULL subscription state argument was provided.

   482      */

   483     virtual TXIMPRequestId SetPresentityGroupContentDataSubscriptionStateL(

   484                 MXIMPIdentity* aGroupId,

   485                 MXIMPDataSubscriptionState* aSubscriptionState,

   486                 MXIMPStatus* aStatus ) = 0;

   487 

   488 

   489     };

   490 

   491 

   492 #endif // MPROTOCOLPRESENTITYGROUPSDATAHOST_H