applayerpluginsandutils/httptransportplugins/httptransporthandler/moutputstream.h
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/applayerpluginsandutils/httptransportplugins/httptransporthandler/moutputstream.h Tue Feb 02 01:09:52 2010 +0200
@@ -0,0 +1,194 @@
+// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of "Eclipse Public License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.eclipse.org/legal/epl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+//
+
+#ifndef __MOUTPUTSTREAM_H__
+#define __MOUTPUTSTREAM_H__
+
+#include <e32std.h>
+
+class MOutputStreamObserver;
+class CX509Certificate;
+
+class MOutputStream
+/**
+The MOutputStream and MOutputStreamObserver classes provide the API to send
+data to a connected remote host. They encapsulate the outbound stream of a
+connected socket.
+
+The output socket observer must bind itself to the output stream before using
+any of the other MOutputStream functions. The MOutputStream::Bind() API is
+used to do this binding. When done for the first time the output stream moves
+from the Idle state to the PendingSend state.
+
+Once an observer has been bound to the output stream data can be sent to the
+connected host using the MOutputStream::SendDataReq() API. This can only be
+done when the output stream is in the PendingSend state otherwise a panic
+occurs. The MOutputStream::SendDataReq() API changes the output stream state
+to the SentData state.
+
+The supplied data buffer must remain valid until the observer is notified
+that the send has been successful. This is done using the
+MOutputStreamObserver::SendDataCnf() API. The output stream moves back to
+the PendingSend state.
+
+The output stream can only be re-bound to another observer when in the
+PendingSend state. The re-binding does not change the state of the output
+stream.
+
+There are two ways to shutdown the stream - asynchronously (standard use) and
+synchronously.
+
+In normal use the asynchronous MOutputSocket::ShutdownReq() API can be used.
+The output stream changes to the Closing state. The observer is notified that
+the stream has closed via the MOutputStreamObserver::OutputStreamCloseInd()
+API. The output stream is then in the Closed state. It is no longer valid to
+use the output stream and to do so will cause an access violation.
+
+With the asynchronous shutdown the corresponding input stream is also shutdown.
+Its observer is notified that the input stream has been closed. Similarly,
+if the corresponding input stream has been shutdown synchronously or
+asynchronously the output stream observer will be notified that the stream
+has been closed.
+
+The MOutputSocket::Close() API closes the output stream synchronously. In
+this case the output stream observer will not be notified. Once the the call
+completes the output stream is in the Closed state and is no longer valid.
+This synchronous close should be used when an asynchronous shutdown is not
+appropriate, e.g. when deleting the observer object in error conditions.
+
+Similar to the asynchronous shutdown the corresponding input stream is also
+shutdown and its observer notified.
+
+The MOutputStream::SecureClientReq() API allows the connection to be upgraded
+to be secure. This request initiates a secure handshake - the local host of
+the connection is the client and the remote host is the server in the
+handshake. During the handshake, the corresponding input stream is suspended -
+no data will be received.
+
+If the secure handshake is successful the output stream observer is notified
+using the MOutputStreamObserver::SecureClientCnf() API. The input stream
+resumes its activity. If the secure handshake was not successful then the
+stream handles the error in the normal manner.
+
+The certificate information for the secure connection can be obtained using
+the MOutputStream::ServerCert() API.
+@see MOutputStreamObserver
+*/
+ {
+public: // methods
+
+/**
+ This binds an observer to the output stream.
+ @param aObserver An output stream observer.
+ @pre The output stream is either in the Idle or PendingSend state.
+ @post The output stream is in the PendingSend state.
+ @panic EBadOutputStreamState The output stream is not in the Idle or
+ PendingSend state.
+*/
+ virtual void Bind(MOutputStreamObserver& aObserver) =0;
+
+/**
+ Requests that the output stream send the supplied data to the connected host.
+ The observer will be notified when the data has been successfully sent. The
+ data buffer must remain valid until this notification.
+ @pre The output stream is in the PendingSend state and an observer has
+ been bound to it.
+ @post The output stream is in the SentData state.
+ @panic EOutputStreamNotBound The output stream has no observer bound
+ to it.
+ @panic EBadOutputStreamState The output stream is not in the
+ PendingSend state.
+*/
+ virtual void SendDataReqL(const TDesC8& aBuffer) =0;
+
+/**
+ Closes the output stream asynchronously. The corresponding input stream is
+ also closed. The output stream observer will be notified when the stream is
+ closed. The corresponding input stream observer is also notified.
+ @pre The output stream is not in the Closing or Closed state and an
+ observer has been bound to it.
+ @post The output stream is in the Closing state.
+ @panic EOutputStreamNotBound The output stream has no observer bound
+ to it.
+ @panic EBadOutputStreamState The output stream is in the Closing or
+ Closed state.
+*/
+ virtual void ShutdownReq() =0;
+
+/**
+ Issue a request to upgrade the client to use a secure connection. The stream
+ will issue a secure handshake and wait for a successful response from the
+ connected host. The corresponding input stream is suspended until the secure
+ handshake completes.
+ @pre The output stream is in the PendingSend state
+ @post The output stream is in the StartSecureHandshake state and the
+ input stream is suspended.
+ @param aHostName The host name of the request used for checking the
+ domain name against the server certificates.
+ @panic EBadOutputStreamState The output stream is not in the PendingSend
+ state.
+*/
+ virtual void SecureClientReq(const TDesC8& aHostName) = 0;
+
+/**
+ Closes the output stream synchronously. The observer is not notified. The
+ corresponding input stream is also closed and its observer notified.
+ @pre The output stream is not in the Closing or Closed state and an
+ observer has been bound to it.
+ @post The output stream is in the Closed state and no longer valid.
+ @panic EOutputStreamNotBound The output stream has no observer bound
+ to it.
+ @panic EBadOutputStreamState The output stream is in the Closing or
+ Closed state.
+*/
+ virtual void Close() =0;
+
+/**
+ Get the Server Certificate for this socket session.
+ @return The server certificate information for the connected host. this may be NULL
+ if the information is not available.
+*/
+ virtual const CX509Certificate* ServerCert() =0;
+
+/**
+ Get the current Cipher Suite for this socket session.
+ @param aCipherSuite A descriptor which will be filled with the cipher suite.
+ This is a 2 digit code as defined by RFC 2246.
+ @return An error code. KErrNone on sucess. KErrNotSupported if this socket session is not secure.
+*/
+ virtual TInt CipherSuite(TDes8& aCipherSuite) = 0;
+
+/**
+ Resets the state to EClosed
+ @componentInternal
+*/
+ virtual void Reset() =0;
+
+/**
+ * Enable/Disable TCP corking during upload
+ *
+ */
+ virtual void SetTCPCorking(TBool aValue) =0;
+
+private: // methods
+
+/**
+ Reserved function for future expansion.
+*/
+ virtual void MOutputStream_Reserved() =0;
+
+ };
+
+#endif // __MOUTPUTSTREAM_H__