|
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 __MOUTPUTSTREAM_H__ |
|
17 #define __MOUTPUTSTREAM_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 |
|
21 class MOutputStreamObserver; |
|
22 class CX509Certificate; |
|
23 |
|
24 class MOutputStream |
|
25 /** |
|
26 The MOutputStream and MOutputStreamObserver classes provide the API to send |
|
27 data to a connected remote host. They encapsulate the outbound stream of a |
|
28 connected socket. |
|
29 |
|
30 The output socket observer must bind itself to the output stream before using |
|
31 any of the other MOutputStream functions. The MOutputStream::Bind() API is |
|
32 used to do this binding. When done for the first time the output stream moves |
|
33 from the Idle state to the PendingSend state. |
|
34 |
|
35 Once an observer has been bound to the output stream data can be sent to the |
|
36 connected host using the MOutputStream::SendDataReq() API. This can only be |
|
37 done when the output stream is in the PendingSend state otherwise a panic |
|
38 occurs. The MOutputStream::SendDataReq() API changes the output stream state |
|
39 to the SentData state. |
|
40 |
|
41 The supplied data buffer must remain valid until the observer is notified |
|
42 that the send has been successful. This is done using the |
|
43 MOutputStreamObserver::SendDataCnf() API. The output stream moves back to |
|
44 the PendingSend state. |
|
45 |
|
46 The output stream can only be re-bound to another observer when in the |
|
47 PendingSend state. The re-binding does not change the state of the output |
|
48 stream. |
|
49 |
|
50 There are two ways to shutdown the stream - asynchronously (standard use) and |
|
51 synchronously. |
|
52 |
|
53 In normal use the asynchronous MOutputSocket::ShutdownReq() API can be used. |
|
54 The output stream changes to the Closing state. The observer is notified that |
|
55 the stream has closed via the MOutputStreamObserver::OutputStreamCloseInd() |
|
56 API. The output stream is then in the Closed state. It is no longer valid to |
|
57 use the output stream and to do so will cause an access violation. |
|
58 |
|
59 With the asynchronous shutdown the corresponding input stream is also shutdown. |
|
60 Its observer is notified that the input stream has been closed. Similarly, |
|
61 if the corresponding input stream has been shutdown synchronously or |
|
62 asynchronously the output stream observer will be notified that the stream |
|
63 has been closed. |
|
64 |
|
65 The MOutputSocket::Close() API closes the output stream synchronously. In |
|
66 this case the output stream observer will not be notified. Once the the call |
|
67 completes the output stream is in the Closed state and is no longer valid. |
|
68 This synchronous close should be used when an asynchronous shutdown is not |
|
69 appropriate, e.g. when deleting the observer object in error conditions. |
|
70 |
|
71 Similar to the asynchronous shutdown the corresponding input stream is also |
|
72 shutdown and its observer notified. |
|
73 |
|
74 The MOutputStream::SecureClientReq() API allows the connection to be upgraded |
|
75 to be secure. This request initiates a secure handshake - the local host of |
|
76 the connection is the client and the remote host is the server in the |
|
77 handshake. During the handshake, the corresponding input stream is suspended - |
|
78 no data will be received. |
|
79 |
|
80 If the secure handshake is successful the output stream observer is notified |
|
81 using the MOutputStreamObserver::SecureClientCnf() API. The input stream |
|
82 resumes its activity. If the secure handshake was not successful then the |
|
83 stream handles the error in the normal manner. |
|
84 |
|
85 The certificate information for the secure connection can be obtained using |
|
86 the MOutputStream::ServerCert() API. |
|
87 @see MOutputStreamObserver |
|
88 */ |
|
89 { |
|
90 public: // methods |
|
91 |
|
92 /** |
|
93 This binds an observer to the output stream. |
|
94 @param aObserver An output stream observer. |
|
95 @pre The output stream is either in the Idle or PendingSend state. |
|
96 @post The output stream is in the PendingSend state. |
|
97 @panic EBadOutputStreamState The output stream is not in the Idle or |
|
98 PendingSend state. |
|
99 */ |
|
100 virtual void Bind(MOutputStreamObserver& aObserver) =0; |
|
101 |
|
102 /** |
|
103 Requests that the output stream send the supplied data to the connected host. |
|
104 The observer will be notified when the data has been successfully sent. The |
|
105 data buffer must remain valid until this notification. |
|
106 @pre The output stream is in the PendingSend state and an observer has |
|
107 been bound to it. |
|
108 @post The output stream is in the SentData state. |
|
109 @panic EOutputStreamNotBound The output stream has no observer bound |
|
110 to it. |
|
111 @panic EBadOutputStreamState The output stream is not in the |
|
112 PendingSend state. |
|
113 */ |
|
114 virtual void SendDataReqL(const TDesC8& aBuffer) =0; |
|
115 |
|
116 /** |
|
117 Closes the output stream asynchronously. The corresponding input stream is |
|
118 also closed. The output stream observer will be notified when the stream is |
|
119 closed. The corresponding input stream observer is also notified. |
|
120 @pre The output stream is not in the Closing or Closed state and an |
|
121 observer has been bound to it. |
|
122 @post The output stream is in the Closing state. |
|
123 @panic EOutputStreamNotBound The output stream has no observer bound |
|
124 to it. |
|
125 @panic EBadOutputStreamState The output stream is in the Closing or |
|
126 Closed state. |
|
127 */ |
|
128 virtual void ShutdownReq() =0; |
|
129 |
|
130 /** |
|
131 Issue a request to upgrade the client to use a secure connection. The stream |
|
132 will issue a secure handshake and wait for a successful response from the |
|
133 connected host. The corresponding input stream is suspended until the secure |
|
134 handshake completes. |
|
135 @pre The output stream is in the PendingSend state |
|
136 @post The output stream is in the StartSecureHandshake state and the |
|
137 input stream is suspended. |
|
138 @param aHostName The host name of the request used for checking the |
|
139 domain name against the server certificates. |
|
140 @panic EBadOutputStreamState The output stream is not in the PendingSend |
|
141 state. |
|
142 */ |
|
143 virtual void SecureClientReq(const TDesC8& aHostName) = 0; |
|
144 |
|
145 /** |
|
146 Closes the output stream synchronously. The observer is not notified. The |
|
147 corresponding input stream is also closed and its observer notified. |
|
148 @pre The output stream is not in the Closing or Closed state and an |
|
149 observer has been bound to it. |
|
150 @post The output stream is in the Closed state and no longer valid. |
|
151 @panic EOutputStreamNotBound The output stream has no observer bound |
|
152 to it. |
|
153 @panic EBadOutputStreamState The output stream is in the Closing or |
|
154 Closed state. |
|
155 */ |
|
156 virtual void Close() =0; |
|
157 |
|
158 /** |
|
159 Get the Server Certificate for this socket session. |
|
160 @return The server certificate information for the connected host. this may be NULL |
|
161 if the information is not available. |
|
162 */ |
|
163 virtual const CX509Certificate* ServerCert() =0; |
|
164 |
|
165 /** |
|
166 Get the current Cipher Suite for this socket session. |
|
167 @param aCipherSuite A descriptor which will be filled with the cipher suite. |
|
168 This is a 2 digit code as defined by RFC 2246. |
|
169 @return An error code. KErrNone on sucess. KErrNotSupported if this socket session is not secure. |
|
170 */ |
|
171 virtual TInt CipherSuite(TDes8& aCipherSuite) = 0; |
|
172 |
|
173 /** |
|
174 Resets the state to EClosed |
|
175 @componentInternal |
|
176 */ |
|
177 virtual void Reset() =0; |
|
178 |
|
179 /** |
|
180 * Enable/Disable TCP corking during upload |
|
181 * |
|
182 */ |
|
183 virtual void SetTCPCorking(TBool aValue) =0; |
|
184 |
|
185 private: // methods |
|
186 |
|
187 /** |
|
188 Reserved function for future expansion. |
|
189 */ |
|
190 virtual void MOutputStream_Reserved() =0; |
|
191 |
|
192 }; |
|
193 |
|
194 #endif // __MOUTPUTSTREAM_H__ |