Add README for examples

Author: MPogotsky

README.md

@@ -97,7 +97,14 @@ Step-by-step guide to build the project using CMake.
     cmake --install . 
     ```
 
-### Runing Tests
+## Usage
+To use xAPI, an active account on the xStation5 trading platform is required. It could be a real account, or demo account. To create one, you can visit [xtb.com](https://www.xtb.com) 
+
+Once your account is set up, you can leverage the Xapi library to connect to the platform and start trading.
+
+For a detailed overview and practical usage of the library, refer to the [**Examples README**](examples/README.md). It contains step-by-step guides and illustrative examples to help you understand how to effectively use the library.
+
+## Runing Tests
 To build the tests, follow these steps:
 
 1. Navigate to the `build` directory.

examples/CMakeLists.txt

@@ -3,6 +3,7 @@ project(ExampleApp)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
 
 find_package(Xapi REQUIRED)
 
@@ -22,3 +23,4 @@ add_example(GetAllSymbols)
 add_example(GetBalance)
 add_example(GetCandles)
 add_example(TradeTransaction)
+add_example(RetrieveStreamSessionId)

examples/GetAllSymbols.cpp

@@ -43,7 +43,7 @@ int main(int argc, char const *argv[])
 {
     boost::asio::io_context context;
 
-    boost::asio::co_spawn(context, run(std::ref(context)), boost::asio::detached);
+    boost::asio::co_spawn(context, run(context), boost::asio::detached);
 
     context.run();
     return 0;

examples/GetBalance.cpp

@@ -58,7 +58,7 @@ int main(int argc, char const *argv[])
 {
     boost::asio::io_context context;
 
-    boost::asio::co_spawn(context, run(std::ref(context)), boost::asio::detached);
+    boost::asio::co_spawn(context, run(context), boost::asio::detached);
 
     context.run();
     return 0;

examples/GetCandles.cpp

@@ -69,7 +69,7 @@ int main(int argc, char const *argv[])
 {
     boost::asio::io_context context;
 
-    boost::asio::co_spawn(context, run(std::ref(context)), boost::asio::detached);
+    boost::asio::co_spawn(context, run(context), boost::asio::detached);
 
     context.run();
     return 0;

examples/README.md

@@ -0,0 +1,90 @@
+# Introduction
+
+Xapi-cpp is a C++ library that provides a simple and easy-to-use API for interacting with the xStation5 trading platform.
+Built on top of the Boost libraries, it leverages Boost’s powerful and widely adopted capabilities, particularly for network-based applications. Boost provides robust, high-performance abstractions that simplify the development of complex asynchronous operations, making it an ideal choice for ensuring a reliable and efficient connection to the xStation5 platform.
+
+## Key Concepts
+
+### 1. Asynchronous Programming with Coroutines
+The library makes heavy use of C++20 coroutines and Boost.Asio to handle asynchronous operations. Each API call is suspended until the operation completes, allowing the program to remain responsive and efficient.
+
+While C++20 provides the coroutine syntax (``co_await``, ``co_return``, ``co_yield``), it doesn’t define a complete framework for asynchronous execution or I/O. Libraries like Boost.Asio provide the necessary abstractions and asynchronous I/O handling that C++20 coroutines on their own do not.
+
+### 2. Secure WebSocket Communication
+The xapi uses secure WebSockets (WebSockets over SSL) for communication, ensuring that the data transmitted between the client and server is encrypted. This provides a secure channel for sensitive information, such as account credentials and balance data.
+
+### 3. Separate WebSocket Connections
+The xapi establishes separate WebSocket connections for **xapi::Socket** and **xapi::Stream**. This separation aims to minimize congestion on a single connection especially if one connection is handling high-frequency data (like streaming).
+
+ 
+# Getting Started
+Let`s break down some important steps to start using xStation in your project
+
+## Awailable operations
+### 1. Socket Operations
+The **xapi::Socket** object is used to Request-Reply commands. Full list of commands is in [xApi Retrieving Trading Data](http://developers.xstore.pro/documentation/2.5.0#retrieving-trading-data)
+
+### 2. Stream Operations
+The **xapi::Stream** object is used to manage real-time streaming data, such as balance updates, tick prises and so on. Full list of streaming operations is in [xApi Available Streaming Commands](http://developers.xstore.pro/documentation/2.5.0#available-streaming-commands)
+
+Please note, that to use streaming operations, you first should get streaming id from **xapi::Socket** login() command.
+
+## Cmake configuration
+Xapi supports ``find_package``, simplifying the process of linking the library to your project. A typical CMake configuration might look like this:
+
+```cmake
+    cmake_minimum_required(VERSION 3.10)
+    project(ExampleApp)
+
+    set(CMAKE_CXX_STANDARD 20)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+    find_package(Xapi REQUIRED)
+
+    add_executable(ExampleApp main.cpp)
+
+    target_link_libraries(ExampleApp
+        PRIVATE
+        Boost::system
+        Boost::json
+        Xapi::Xapi
+    )
+```
+
+
+## Simple example
+The simplest example is [RetrieveStreamSessionId](RetrieveStreamSessionId.cpp), which demonstrates how to connect to an xStation server using Xapi. The program initializes a session, logs in, and retrieves a stream session ID.
+
+Additional examples can be found in the .cpp files within the examples folder.
+
+## Compile examples
+You can compile all examples by following these steps:
+
+1. Fix your credentials in the example you want to use. In ``run`` function:
+
+    ```cpp
+    const std::string accountId = "<your accountId>";
+    const std::string password = "<your password>";
+
+    // If you are using real account, replace with "real"
+    const std::string accountType = "demo";
+    ```
+
+1. Create a `build` directory and navigate into it:
+
+    ```bash
+    mkdir build
+    cd build
+    ```
+
+2. Run CMake to configure and build the project:
+
+    ```bash
+    cmake ..
+    cmake --build . 
+    ```
+
+3. Binaries will be stored in ``bin`` directory. Run example app that you want (f.e. RetrieveStreamSessionId)
+    ```bash
+    ./bin/RetrieveStreamSessionId
+    ```

examples/RetrieveStreamSessionId.cpp

@@ -0,0 +1,51 @@
+#include <iostream>
+#include <string>
+
+#include <boost/asio.hpp>
+#include <boost/json.hpp>
+#include <xapi/Xapi.hpp>
+
+
+boost::asio::awaitable<void> run(boost::asio::io_context &context)
+{
+    xapi::Socket socket(context);
+
+    // Replace with your actual credentials
+    const std::string accountId = "accountId";
+    const std::string password = "password";
+
+    // If you are using real account, replace with "real"
+    const std::string accountType = "demo";
+
+    try
+    {
+        co_await socket.initSession(accountType);
+        auto streamsessionId = co_await socket.login(accountId, password);
+        
+        std::cout << "Stream session id: " << streamsessionId << std::endl;
+
+        co_await socket.closeSession();
+    }
+    catch (xapi::exception::ConnectionClosed &e)
+    {
+        std::cout << "Connection failed: " << e.what() << std::endl;
+    }
+    catch (xapi::exception::LoginFailed &e)
+    {
+        std::cout << "Logging failed: " << e.what() << std::endl;
+    }
+    catch (std::exception &e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+}
+
+int main(int argc, char const *argv[])
+{
+    boost::asio::io_context context;
+
+    boost::asio::co_spawn(context, run(context), boost::asio::detached);
+
+    context.run();
+    return 0;
+}

examples/TradeTransaction.cpp

@@ -95,7 +95,7 @@ int main(int argc, char const *argv[])
 {
     boost::asio::io_context context;
 
-    boost::asio::co_spawn(context, run(std::ref(context)), boost::asio::detached);
+    boost::asio::co_spawn(context, run(context), boost::asio::detached);
 
     context.run();
     return 0;