1 /* |
|
2 * Copyright (c) 2004 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: Messenger interface: provides two-way communication between |
|
15 * two or more clients. |
|
16 * |
|
17 */ |
|
18 |
|
19 |
|
20 #ifndef CPhCltMessenger_H |
|
21 #define CPhCltMessenger_H |
|
22 #include <etelmm.h> |
|
23 |
|
24 // FORWARD DECLARATIONS |
|
25 class RPhCltServer; |
|
26 |
|
27 // The default Messenger data size. |
|
28 const TInt KPhCltDefMesSize = 64; |
|
29 |
|
30 |
|
31 /** |
|
32 * Enumerates asynchronous messenger requests. |
|
33 * |
|
34 * @since 2.6. |
|
35 * |
|
36 * EPhCltMesRequestReceive - request corresponding to the Receive method. |
|
37 * EPhCltMesRequestSend - request corresponding to the Send method. |
|
38 */ |
|
39 enum TPhCltMessengerRequest |
|
40 { |
|
41 EPhCltMesRequestReceive = 1, |
|
42 EPhCltMesRequestSend = 2 |
|
43 }; |
|
44 |
|
45 |
|
46 |
|
47 |
|
48 /** |
|
49 * Messenger Negotiator commands. |
|
50 * |
|
51 * EPhCltMesCommandUnknown The command was unknown. |
|
52 * |
|
53 * EPhCltMesCommandSend The Send command. |
|
54 * EPhCltMesCommandReceive The Receive command. |
|
55 * EPhCltMesCommandSkip The Skip command. |
|
56 * |
|
57 * EPhCltMesConstruct The Construct command. |
|
58 * EPhCltMesCommandDelete The Delete command. |
|
59 * |
|
60 * EPhCltMesCommandCancelSend Send request canceled. |
|
61 * EPhCltMesCommandCancelReceive Receive request canceled. |
|
62 */ |
|
63 enum TPhCltMessengerCommand |
|
64 { |
|
65 EPhCltMesCommandUnknown = 0, |
|
66 |
|
67 EPhCltMesCommandReceive = 1, |
|
68 EPhCltMesCommandSend = 2, |
|
69 EPhCltMesCommandSkip = 3, |
|
70 |
|
71 EPhCltMesCommandConstruct = 4, |
|
72 EPhCltMesCommandDelete = 5, |
|
73 |
|
74 EPhCltMesCommandCancelSend = 6, |
|
75 EPhCltMesCommandCancelReceive = 7 |
|
76 }; |
|
77 |
|
78 /** |
|
79 * The parameter storage class used in PhoneClient and PhoneServer |
|
80 * data transfer. |
|
81 * |
|
82 * @since 2.6. |
|
83 */ |
|
84 class TPhCltMessengerParameters |
|
85 { |
|
86 public: // Constructors and destructor |
|
87 |
|
88 /** |
|
89 * Constructor. |
|
90 */ |
|
91 inline TPhCltMessengerParameters() : |
|
92 iMessengerCommand( EPhCltMesCommandUnknown ), |
|
93 iDefaultMessageSize( 0 ), |
|
94 iReceiveMessageSizePtr( NULL ), |
|
95 iReceiveBufferMaxSize( 0 ), |
|
96 iSendPayloadLength( 0 ), |
|
97 iCancelRequest( EPhCltMesRequestReceive ) |
|
98 { |
|
99 } |
|
100 |
|
101 public: // Data |
|
102 |
|
103 // The Messenger Negotiator command. |
|
104 TPhCltMessengerCommand iMessengerCommand; |
|
105 |
|
106 // The message types that are listened. |
|
107 TUid iCategoryUid; |
|
108 |
|
109 // The default message size. |
|
110 TInt iDefaultMessageSize; |
|
111 |
|
112 // The pointer to the descriptor that contains the |
|
113 // received message size TInt. |
|
114 TAny* iReceiveMessageSizePtr; |
|
115 |
|
116 // The maximum size of the receive buffer. |
|
117 TInt iReceiveBufferMaxSize; |
|
118 |
|
119 // The length of the Send data. |
|
120 TInt iSendPayloadLength; |
|
121 |
|
122 // The canceled command. |
|
123 TPhCltMessengerRequest iCancelRequest; |
|
124 }; |
|
125 |
|
126 /** |
|
127 * Messenger interface: provides two-way communication between |
|
128 * two or more clients. |
|
129 * Meant for Phone and Video Telephony application information transfer. |
|
130 * |
|
131 * @lib PhoneClient.lib |
|
132 * @since 3.2 |
|
133 */ |
|
134 class CPhCltMessenger : public CBase |
|
135 { |
|
136 |
|
137 public: // Constructors |
|
138 |
|
139 /** |
|
140 * Two-phased constructor. |
|
141 * |
|
142 * @param aCategoryUid Category of messages to be sent or received. |
|
143 * Note that there can be many kinds of message uids |
|
144 * below one category uid. |
|
145 * @param aDefaultMessageSize The default size of the messages to be sent |
|
146 * or received in bytes. Can be bigger than |
|
147 * KPhCltDefMesSize, but then functionality |
|
148 * is not guaranteed. |
|
149 */ |
|
150 IMPORT_C static CPhCltMessenger* NewL( const TUid& aCategoryUid, |
|
151 const TInt& aDefaultMessageSize ); |
|
152 |
|
153 public: // New functions |
|
154 |
|
155 /** |
|
156 * Receives next message. No memory is allocated during the operation of |
|
157 * this method. |
|
158 * |
|
159 * @param aStatus This request will be completed once message has been |
|
160 * received. |
|
161 * @param aMessageSize Tells the size of the received message. If bigger |
|
162 * than the size of the aMessagePayload, then only the beginning |
|
163 * of the received message is copied to aMessagePayload. This |
|
164 * means that either Receive must be called with bigger buffer to |
|
165 * receive full message or Skip must be called to indicate that |
|
166 * the full message is not needed. |
|
167 * |
|
168 * @param aMessagePayload Storage to the message to be received. The |
|
169 * format of the message is determined by the |
|
170 * category Uid used in Open method. |
|
171 * . |
|
172 */ |
|
173 IMPORT_C virtual void Receive( |
|
174 TRequestStatus& aStatus, |
|
175 TInt& aMessageSize, |
|
176 TDes8& aMessagePayload ) = 0; |
|
177 |
|
178 |
|
179 /** |
|
180 * Sends message. This is completed only after message has been |
|
181 * delivered to all receivers of the same category. |
|
182 * No memory is allocated during the operation of this method. |
|
183 * |
|
184 * @param aStatus This request will be completed once message has been |
|
185 * sent. |
|
186 * @param aMessagePayload The sent message.The format of the message is |
|
187 * determined by the category Uid used in Open method. |
|
188 */ |
|
189 IMPORT_C virtual void Send( |
|
190 TRequestStatus& aStatus, |
|
191 const TDesC8& aMessagePayload ) = 0; |
|
192 |
|
193 |
|
194 /** |
|
195 * Cancel request. This method should only be called in destruction |
|
196 * to make sure that messages are not missed. |
|
197 * |
|
198 * @param aRequest request to be canceled. |
|
199 */ |
|
200 IMPORT_C virtual void CancelRequest( |
|
201 const TPhCltMessengerRequest& aRequest ) = 0; |
|
202 |
|
203 |
|
204 /** |
|
205 * Skip one (i.e. next) message. This method should be called only if |
|
206 * Receive completion indicates that there is not enough space in |
|
207 * aMessagePayload. |
|
208 * Of course, you should attempt to recover, i.e. try to call Receive |
|
209 * with big enough aMessagePayload buffer before calling this method. |
|
210 */ |
|
211 virtual void Skip() = 0; |
|
212 |
|
213 protected: |
|
214 |
|
215 /** |
|
216 * C++ constructor. |
|
217 */ |
|
218 CPhCltMessenger(); |
|
219 |
|
220 }; |
|
221 |
|
222 |
|
223 #endif // CPhCltMessenger_H |
|
224 |
|
225 // End of File |
|