1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class implements Comms client endpoint. Client

    15 *                endpoint can be connected to server endpoint and it forwards

    16 *                received messages to listeners.

    17 *

    18 */

    19 

    20 #ifndef COMMSCLIENTENDPOINT_H

    21 #define COMMSCLIENTENDPOINT_H

    22 #include <memory>

    23 

    24 #include "transport.h"

    25 

    26 #include "commsendpoint.h"

    27 

    28 namespace java

    29 {

    30 namespace comms

    31 {

    32 class CommsMessage;

    33 

    34 /**

    35 * This class implements Comms client endpoint. Client endpoint can be connected to server

    36 * endpoint and it forwards received messages to listeners.

    37 *

    38 * Comms endpoint provides interprocess communication functionality. Comms communication

    39 * is point-to-point meaning that client endpoint can be connected to a single server at a time.

    40 * Communication is message based, where users wrap their payload to CommsMessage.

    41 * Comms endpoints support synchronous and asynchronous message sending.

    42 *

    43 * CommsListener provides a way to receive messages asynchronously. Listeners are registered

    44 * to endpoint. When message belonging to listener is received, will Comms endpoint make a

    45 * callback for listener. Application can register as many listeners as need.

    46 *

    47 * Application can register also a default listener, which gets called if there is no registered

    48 * listener for received message.

    49 *

    50 * CommsClientEndpoint is thread safe.

    51 *

    52 * Usage:

    53 * It is recomended that at least default listener is registered before CommsClientEndpoint

    54 * is connected. This ensures that no messages are lost.

    55 * @code

    56 * CommsClientEndpoint comms;

    57 * comms.registerDefaultListener(listener);

    58 * comms.connect(MY_SERVER_NAME);

    59 * ...

    60 * comms.disconnect();

    61 * @endcode

    62 *

    63 * @see CommsListener, CommsServerEndpoint, CommsEndpoint

    64 */

    65 class CommsClientEndpoint : public CommsEndpoint

    66 {

    67 public:

    68     /**

    69     * A default constructor.

    70     */

    71     OS_IMPORT CommsClientEndpoint();

    72 

    73     /**

    74     * Creates a named endpoint. Reference to this endpoint can be acquired via find() method.

    75     * Named endpoint is useful e.g. in situations where same endpoint needs to be shared between

    76     * native and java sides.

    77     * @see find()

    78     */

    79     OS_IMPORT CommsClientEndpoint(const std::wstring& aName);

    80 

    81     /**

    82     * A destructor.

    83     */

    84     OS_IMPORT virtual ~CommsClientEndpoint();

    85 

    86     /**

    87     * Finds a named endpoint.

    88     * @param[in] aName Endpoint name

    89     * @see CommsClientEndpoint()

    90     * @return Endpoint in success, 0 in failure

    91     */

    92     OS_IMPORT static CommsClientEndpoint* find(const std::wstring& name);

    93 

    94     /**

    95     * Connects to a named endpoint.

    96     * Endpoint needs to be connected before messages can be sent or received.

    97     * It's recommended that at least one listener is registered before connecting to server.

    98     * @code

    99     * CommsClientEndpoint comms;

   100     * int rc = comms.connect(MY_SERVER_NAME);

   101     * if(rc!=0)

   102     * {

   103     *     cout << "connect failed";

   104     * }

   105     * @endcode

   106     * @param[in] aAddress Server name

   107     * @see disconnect()

   108     * @see registerListener()

   109     * @return 0 in success, errno in failure

   110     */

   111     OS_IMPORT virtual int connect(int aAddress);

   112 

   113     /**

   114     * Disconnects from from server endpoint. Messages can not be sent or received after this call.

   115     * Applicaton can reconnect again using connect() method.

   116     * Listeners remain registered after this method call so listeners do not need to re-registered.

   117     * @code

   118     * CommsClientEndpoint comms;

   119     * comms.connect(MY_SERVER_NAME);

   120     * comms.disconnect();

   121     * @endcode

   122     * @param -

   123     * @see connect()

   124     * @see registerListener()

   125     * @return 0 in success, errno in failure

   126     */

   127     OS_IMPORT virtual int disconnect();

   128 

   129     /**

   130     * Sends a message.

   131     *

   132     * See description from CommsEndpoint::send().

   133     * @param[in] aMessage A message to be sent

   134     * @see sendReceive()

   135     * @see registerListener()

   136     * @return 0 in success, errno in failure

   137     */

   138     OS_IMPORT virtual int send(CommsMessage& aMessage);

   139 

   140     OS_IMPORT virtual int detachFromVm();

   141 private:

   142     std::auto_ptr<IpcConnectionInterface> mIpc;

   143     int mAddress;

   144     const bool mAddedToContext;

   145 };

   146 

   147 } // namespace comms

   148 } // namespace java

   149 

   150 #endif // COMMSCLIENTENDPOINT_H