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 __MSOCKETFACTORY_H__

    17 #define __MSOCKETFACTORY_H__

    18 

    19 #include <e32std.h>

    20 

    21 class MSocketConnectObserver;

    22 class MSocketListenObserver;

    23 class MSocketConnector;

    24 

    25 class MSocketFactory

    26 /**	

    27 The MSocketFactory class provides an API to obtain connected sockets. There

    28 are two methods of obtaining these connected sockets. The first is via a

    29 listening service on a specified local port that receives connections. The

    30 second method is a connecting service that initiates a connection to a 

    31 specified port on a specified remote host.

    32 

    33 The listening service requires an observer - an MSocketListenObserver. The

    34 observer is notified of either a received connection or of any errors that

    35 occur in the listening service. If a connection is received, the listening

    36 service continues. If an error occurs the listening service stops. There can

    37 be only a single listening service. Attempting to start a second service 

    38 will cause a panic. The listening service can be stopped at any time.

    39 

    40 The connecting service also requires an observer - an MSocketConnectObserver.

    41 There can be many connecting services active at any one time. Each one has

    42 an associated socket connector - MSocketConnector. This API allows each 

    43 connection request to be stopped at any time before the connection ends. The

    44 connection is ended when the socket connect observer has been notified of 

    45 either a successful connection or of an error occuring during the connection.

    46 Attempting to stop the socket connector after either of these notifications

    47 will cause an access violation - the socket connector is no longer valid.

    48 @see		MSocketListenObserver

    49 @see		MSocketConnectObserver

    50 @see		MSocketConnector

    51 */

    52 	{

    53 public:	// methods

    54 

    55 /**	

    56 	This function requests that a listening service be started on the specified

    57 	port. This service listens for remote hosts making a connection with the 

    58 	specified port. 

    59 	@param		aObserver	The observer object for the listen service.

    60 	@param		aPort		The local port that should listen for connections.

    61 	@panic		EBadSocketListenerState	The listening service has already been started.

    62 */

    63 	virtual void ListenL(MSocketListenObserver& aObserver, TUint16 aPort) =0;

    64 	

    65 /**	

    66 	Terminate the listening service. The listen observer will be notified on the

    67 	MSocketListenObserver::HandleListenError() API with an error code of 

    68 	KErrCancel when the listen service has actual stopped.

    69 	@panic		EInvariantFalse	The listening service has not been started.

    70 */

    71 	virtual void StopListen() =0;

    72 

    73 /**	

    74 	Requests that a connection is attempted with the specified port on the 

    75 	specified remote host. The IP address can be either a numeric address or a

    76 	host name.

    77 	@param		aObserver		The observer object for this connection.

    78 	@param		aRemoteHost		The host name/IP address of the remote client.

    79 	@param		aRemotePort		The port number of the remote client.

    80 	@return		The socket connector that encapsulates the connection.

    81 	@leave		KErrNoMemory

    82 */

    83 	virtual MSocketConnector& ConnectL(MSocketConnectObserver& aObserver, const TDesC8& aRemoteHost, TUint16 aRemotePort) =0;

    84 

    85 private:	// methods

    86 

    87 /**	

    88 	Reserved function for future expansion.

    89 */

    90 	virtual void MSocketFactory_Reserved() =0;

    91 

    92 	};

    93 

    94 #endif	// __MSOCKETFACTORY_H__