diff -r 000000000000 -r b16258d2340f 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 + +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__