|
1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __MOUTPUTSTREAMOBSERVER_H__ |
|
17 #define __MOUTPUTSTREAMOBSERVER_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 |
|
21 class MOutputStreamObserver |
|
22 /** |
|
23 The MOutputStream and MOutputStreamObserver classes provide the API to send |
|
24 data to a connected remote host. They encapsulate the outbound stream of a |
|
25 connected socket. |
|
26 |
|
27 The output socket observer must bind itself to the output stream before using |
|
28 any of the other MOutputStream functions. The MOutputStream::Bind() API is |
|
29 used to do this binding. When done for the first time the output stream moves |
|
30 from the Idle state to the PendingSend state. |
|
31 |
|
32 Once an observer has been bound to the output stream data can be sent to the |
|
33 connected host using the MOutputStream::SendDataReq() API. This can only be |
|
34 done when the output stream is in the PendingSend state otherwise a panic |
|
35 occurs. The MOutputStream::SendDataReq() API changes the output stream state |
|
36 to the SentData state. |
|
37 |
|
38 The supplied data buffer must remain valid until the observer is notified |
|
39 that the send has been successful. This is done using the |
|
40 MOutputStreamObserver::SendDataCnf() API. The output stream moves back to |
|
41 the PendingSend state. |
|
42 |
|
43 The output stream can only be re-bound to another observer when in the |
|
44 PendingSend state. The re-binding does not change the state of the output |
|
45 stream. |
|
46 |
|
47 There are two ways to shutdown the stream - asynchronously (standard use) and |
|
48 synchronously. |
|
49 |
|
50 In normal use the asynchronous MOutputSocket::ShutdownReq() API can be used. |
|
51 The output stream changes to the Closing state. The observer is notified that |
|
52 the stream has closed via the MOutputStreamObserver::OutputStreamCloseInd() |
|
53 API. The output stream is then in the Closed state. It is no longer valid to |
|
54 use the output stream and to do so will cause an access violation. |
|
55 |
|
56 With the asynchronous shutdown the corresponding input stream is also shutdown. |
|
57 Its observer is notified that the input stream has been closed. Similarly, |
|
58 if the corresponding input stream has been shutdown synchronously or |
|
59 asynchronously the output stream observer will be notified that the stream |
|
60 has been closed. |
|
61 |
|
62 The MOutputSocket::Close() API closes the output stream synchronously. In |
|
63 this case the output stream observer will not be notified. Once the the call |
|
64 completes the output stream is in the Closed state and is no longer valid. |
|
65 This synchronous close should be used when an asynchronous shutdown is not |
|
66 appropriate, e.g. when deleting the observer object in error conditions. |
|
67 |
|
68 Similar to the asynchronous shutdown the corresponding input stream is also |
|
69 shutdown and its observer notified. |
|
70 |
|
71 The MOutputStream::SecureClientReq() API allows the connection to be upgraded |
|
72 to be secure. This request initiates a secure handshake - the local host of |
|
73 the connection is the client and the remote host is the server in the |
|
74 handshake. During the handshake, the corresponding input stream is suspended - |
|
75 no data will be received. |
|
76 |
|
77 If the secure handshake is successful the output stream observer is notified |
|
78 using the MOutputStreamObserver::SecureClientCnf() API. The input stream |
|
79 resumes its activity. If the secure handshake was not successful then the |
|
80 stream handles the error in the normal manner. |
|
81 |
|
82 The certificate information for the secure connection can be obtained using |
|
83 the MOutputStream::ServerCert() API. |
|
84 @see MOutputStream |
|
85 */ |
|
86 { |
|
87 public: // methods |
|
88 |
|
89 /** |
|
90 Notifies the output stream observer that the data has been succeessfully |
|
91 sent to the remote host. |
|
92 @post The output stream in the PendingSend state. |
|
93 */ |
|
94 virtual void SendDataCnfL() =0; |
|
95 |
|
96 /** |
|
97 Notifies the output stream observer that secure upgrade on the connection |
|
98 has completed successfully. |
|
99 @post The output stream in the PendingSend state. |
|
100 */ |
|
101 virtual void SecureClientCnf() =0; |
|
102 |
|
103 /** |
|
104 Notifies the output stream observer that the socket connection with the |
|
105 remote host has been closed. The output stream is no longer valid. |
|
106 @param aError The error code explaining why the socket connection has |
|
107 closed. A value of KErrNone indicates that either the |
|
108 input or output stream observer requested that the |
|
109 socket connection be closed. |
|
110 @post The output stream is in the Closed state and is no longer valid. |
|
111 */ |
|
112 virtual void OutputStreamCloseInd(TInt aError) =0; |
|
113 |
|
114 virtual void OnSendTimeOut() =0; |
|
115 |
|
116 virtual TInt SendTimeOutVal() =0; |
|
117 |
|
118 private: // methods |
|
119 |
|
120 /** |
|
121 Reserved function for future expansion. |
|
122 */ |
|
123 virtual void MOutputStreamObserver_Reserved() =0; |
|
124 |
|
125 }; |
|
126 |
|
127 #endif // __MOUTPUTSTREAMOBSERVER_H__ |