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 server endpoint. Server

    15 *                endpoint waits for incoming connections and it forwards

    16 *                received messages to listeners.

    17 *

    18 */

    19 

    20 #ifndef COMMSSERVERENDPOINT_H

    21 #define COMMSSERVERENDPOINT_H

    22 #include <memory>

    23 

    24 #include "transport.h"

    25 

    26 #include "commsendpoint.h"

    27 

    28 namespace java

    29 {

    30 namespace comms

    31 {

    32 

    33 class CommsMessage;

    34 

    35 /**

    36 * This class implements Comms server endpoint. Server endpoint waits for incoming

    37 * connections and it forwards received messages to listeners.

    38 *

    39 * Comms endpoint provides interprocess communication functionality. Comms communication

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

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

    42 * Comms endpoints support synchronous and asynchronous message sending.

    43 *

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

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

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

    47 *

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

    49 * listener for received message.

    50 *

    51 * CommsServerEndpoint is thread safe.

    52 *

    53 * Usage:

    54 * It is recomended that at least default listener is registered before CommsServerEndpoint

    55 * is started. This ensures that no messages are lost.

    56 * @code

    57 * CommsServerEndpoint comms;

    58 * comms.registerDefaultListener(listener);

    59 * comms.start(MY_SERVER_NAME);

    60 * ...

    61 * comms.stop();

    62 * @endcode

    63 *

    64 * @see CommsListener, CommsClientEndpoint, CommsEndpoint

    65 */

    66 class CommsServerEndpoint : public CommsEndpoint

    67 {

    68 public:

    69     /**

    70     * A default constructor.

    71     */

    72     OS_IMPORT CommsServerEndpoint();

    73 

    74     /**

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

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

    77     * native and java sides.

    78     * @see find()

    79     */

    80     OS_IMPORT CommsServerEndpoint(const std::wstring& aName);

    81 

    82     /**

    83     * A destructor.

    84     */

    85     OS_IMPORT virtual ~CommsServerEndpoint();

    86 

    87     /**

    88     * Finds a named endpoint.

    89     * @param[in] aName Endpoint name

    90     * @see CommsClientEndpoint()

    91     * @return Endpoint in success, 0 in failure

    92     */

    93     OS_IMPORT static CommsServerEndpoint* find(const std::wstring& name);

    94 

    95     /**

    96     * Start to listen for incoming connections.

    97     * Once server endpoint is started, clients can connect to it using it's 'well-know' name.

    98     * Multiple clients can be connected to the same server. Server endpoint dispatches received

    99     * messages to registered listeners. It's recommended that at least one listener is

   100     * registered before starting endpoint.

   101     * @code

   102     * CommsServerEndpoint comms;

   103     * int rc = comms.start(MY_SERVER_NAME);

   104     * if(rc!=0)

   105     * {

   106     *     cout << "start server failed";

   107     * }

   108     * @endcode

   109     * @param[in] aAddress Server name

   110     * @see stop()

   111     * @see registerListener()

   112     * @return 0 in success, errno in failure

   113     */

   114     OS_IMPORT virtual int start(int aAddress);

   115 

   116     /**

   117     * Stops listening for incoming connecections.

   118     * Messages can not be sent or received after this call and clients are not able to connect

   119     * to server.

   120     * Applicaton can start to listen again using start() method.

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

   122     * themselves.

   123     * @code

   124     * CommsServerEndpoint comms;

   125     * comms.start(MY_SERVER_NAME);

   126     * comms.stop();

   127     * @endcode

   128     * @param -

   129     * @see start()

   130     * @see registerListener()

   131     * @return 0 in success, errno in failure

   132     */

   133     OS_IMPORT virtual int stop();

   134 

   135     /**

   136     * Sends a message.

   137     *

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

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

   140     * @see sendReceive()

   141     * @see registerListener()

   142     * @return 0 in success, errno in failure

   143     */

   144     OS_IMPORT virtual int send(CommsMessage& aMessage);

   145 

   146     OS_IMPORT virtual int detachFromVm();

   147 private:

   148     std::auto_ptr<IpcServerConnectionInterface> mIpc;

   149     int mAddress;

   150     const bool mAddedToContext;

   151 };

   152 

   153 } // namespace comms

   154 } // namespace java

   155 

   156 #endif // COMMSSERVERENDPOINT_H

   157