|
1 // Copyright (c) 2001-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 __MINPUTSTREAM_H__ |
|
17 #define __MINPUTSTREAM_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 |
|
21 class MInputStreamObserver; |
|
22 class CX509Certificate; |
|
23 |
|
24 class MInputStream |
|
25 /** |
|
26 The MInputStream and MInputStreamObserver classes provide the API to receive |
|
27 data from a connected remote host. They encapsulate the inbound stream of a |
|
28 connected socket. |
|
29 |
|
30 The input socket observer must bind itself to the input stream before using |
|
31 any of the other MInputStream functions. The MInputStream::Bind() API is |
|
32 used to do this binding. The input stream does not do its first read until |
|
33 an observer has been bound to it. When done for the first time the input |
|
34 stream moves from the Idle state to the Read state. |
|
35 |
|
36 When the input stream is in the Read state, it requests a read from the |
|
37 socket. This moves the input stream into the ReceivedData state and it waits |
|
38 for the socket to notify it when it receives any data from the remote host. |
|
39 When the input stream receives the notification it notifies its observer via |
|
40 the MInputStreamObserver::ReceivedDataInd() API. The input stream moves into |
|
41 the PendingAck state. |
|
42 |
|
43 The buffer containing the received data remains valid until the observer |
|
44 notifies the input stream that it is no longer needed. The observer can do |
|
45 this using the MInputStream::ReceivedDataRes() API. The input stream returns |
|
46 to the Read state and issues another read request to the socket. |
|
47 |
|
48 The input stream can only be re-bound to another observer when it is in the |
|
49 PendingAck state. This does not change the state of the input stream. The |
|
50 new observer is responsible for notifying the input stream when the received |
|
51 data buffer is no longer needed. |
|
52 |
|
53 There are two ways to shutdown the stream - asynchronously (standard use) and |
|
54 synchronously. |
|
55 |
|
56 In normal use the asynchronous MInputSocket::ShutdownReq() API can be used. |
|
57 The input stream changes to the Closing state. The observer is notified that |
|
58 the stream has closed via the MInputStreamObserver::InputStreamCloseInd() |
|
59 API. The input stream is then in the Closed state. It is no longer valid to |
|
60 use the input stream and to do so will cause an access violation. |
|
61 |
|
62 With the asynchronous shutdown the corresponding output stream is also shutdown. |
|
63 Its observer is notified that the output stream has been closed. Similarly, |
|
64 if the corresponding output stream has been shutdown sychronously or |
|
65 asynchronously the input stream observer will be notified that the stream |
|
66 has been closed. |
|
67 |
|
68 The MInputSocket::Close() API closes the input stream synchronously. In |
|
69 this case the observer will not be notified. Once the the call completes |
|
70 the input stream is in the Closed state and is no longer valid. This |
|
71 synchronous close should be used when an asynchronous shutdown is not |
|
72 appropriate, e.g. when deleting the observer object in error conditions. |
|
73 |
|
74 Similar to the asynchronous shutdown the corresponding output stream is also |
|
75 shutdown and its observer notified. |
|
76 @see MInputStreamObserver |
|
77 */ |
|
78 { |
|
79 public: // methods |
|
80 |
|
81 /** |
|
82 This binds an observer to the input stream. The bound observer is responsible |
|
83 for notifying the input stream when the current received data (if any) is no |
|
84 longer needed. |
|
85 @param aObserver An input stream observer. |
|
86 @pre The input stream is either in the Idle or PendingAck state. |
|
87 @post The input stream is in the Read state if the previous state was |
|
88 the Idle state, or it remains in the PendingAck state. |
|
89 @panic EBadInputStreamState The input stream is not in the Idle or |
|
90 PendingAck state. |
|
91 @internalComponent |
|
92 */ |
|
93 virtual void Bind(MInputStreamObserver& aObserver) =0; |
|
94 |
|
95 /** |
|
96 Informs the input stream that the received data is no longer needed. The |
|
97 input stream can request a read from the socket. |
|
98 @pre The input stream is in the PendingAck state and an observer has |
|
99 been bound to it. |
|
100 @post The input stream is in the Read state. |
|
101 @panic EInputStreamNotBound The input stream has no observer bound |
|
102 to it. |
|
103 @panic EBadInputStreamState The input stream is not in the EPendingAck |
|
104 state. |
|
105 @internalComponent |
|
106 */ |
|
107 virtual void ReceivedDataRes() =0; |
|
108 |
|
109 /** |
|
110 Closes the input stream asynchronously. The corresponding output stream is |
|
111 also closed. The input stream observer will be notified when the stream is |
|
112 closed. The corresponding output stream observer is also notified. |
|
113 @pre The input stream is not in the Closing or Closed state and an |
|
114 observer has been bound to it. |
|
115 @post The input stream is in the Closing state. |
|
116 @panic EInputStreamNotBound The input stream has no observer bound |
|
117 to it. |
|
118 @panic EBadInputStreamState The input stream is in the Closing or |
|
119 Closed state. |
|
120 @internalComponent |
|
121 */ |
|
122 virtual void ShutdownReq() =0; |
|
123 |
|
124 /** |
|
125 Requests that the connection upgrade to a secure connection. The stream will |
|
126 wait for to receive a secure handshake. |
|
127 @internalComponent |
|
128 */ |
|
129 virtual void SecureServerReq() = 0; |
|
130 |
|
131 /** |
|
132 Closes the input stream synchronously. The observer is not notified. The |
|
133 corresponding output stream is also closed and its observer notified. |
|
134 @pre The input stream is not in the Closing or Closed state and an |
|
135 observer has been bound to it. |
|
136 @post The input stream is in the Closed state and no longer valid. |
|
137 @panic EInputStreamNotBound The input stream has no observer bound |
|
138 to it. |
|
139 @panic EBadInputStreamState The input stream is in the Closing or |
|
140 Closed state. |
|
141 @internalComponent |
|
142 */ |
|
143 virtual void Close() =0; |
|
144 |
|
145 /** |
|
146 Get the Client Certificate for this socket session. |
|
147 @return The server certificate information for the connected host. this may be NULL |
|
148 if the information is not available. |
|
149 @internalComponent |
|
150 */ |
|
151 virtual const CX509Certificate* ClientCert() =0; |
|
152 |
|
153 /** |
|
154 Resets the state to EClosed |
|
155 @internalComponent |
|
156 */ |
|
157 virtual void Reset() =0; |
|
158 |
|
159 virtual TInt ImmediateRead ( TPtrC8& aData ) =0; |
|
160 |
|
161 virtual void Restart () =0; |
|
162 |
|
163 virtual void StartReceieveTimer (TInt aTimeoutValue) =0; |
|
164 |
|
165 /** |
|
166 Reserved function for future expansion. |
|
167 */ |
|
168 virtual void Shutdown() =0; |
|
169 |
|
170 }; |
|
171 |
|
172 #endif // __MINPUTSTREAM_H__ |