Skip to content

Commit deae5ce

Browse files
hfosslihfossli
committed
Restructuring readme
1 parent f02dc68 commit deae5ce

File tree

5 files changed

+345
-286
lines changed

5 files changed

+345
-286
lines changed

‎API.md

+196
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
## API
2+
### *Overview*
3+
There're just 3 roles in this library - `socket`,`client` and `message`.
4+
5+
`client` is for physical connection while `socket` is for "namespace"(which is like a logical channel), which means one `socket` paired with one namespace, and one `client` paired with one physical connection.
6+
7+
Since a physical connection can have multiple namespaces (which is called multiplex), a `client` object may have multiple `socket` objects, each is bind to a distinct `namespace`.
8+
9+
Use `client` to setup the connection to the server, manange the connection status, also session id for the connection.
10+
11+
Use `socket` to send messages under namespace and receives messages in the namespace, also handle special types of message.
12+
13+
The `message` is just about the content you want to send, with text,binary or structured combinations.
14+
15+
### *Socket*
16+
#### Constructors
17+
Sockets are all managed by `client`, no public constructors.
18+
19+
You can get it's pointer by `client.socket(namespace)`.
20+
21+
#### Event Emitter
22+
`void emit(std::string const& name, message::list const& msglist, std::function<void (message::ptr const&)> const& ack)`
23+
24+
Universal event emition interface, by applying implicit conversion magic, it is backward compatible with all previous `emit` interfaces.
25+
26+
#### Event Bindings
27+
`void on(std::string const& event_name,event_listener const& func)`
28+
29+
`void on(std::string const& event_name,event_listener_aux const& func)`
30+
31+
Bind a callback to specified event name. Same as `socket.on()` function in JS, `event_listener` is for full content event object,`event_listener_aux` is for convinience.
32+
33+
`void off(std::string const& event_name)`
34+
35+
Unbind the event callback with specified name.
36+
37+
`void off_all()`
38+
39+
Clear all event bindings (not including the error listener).
40+
41+
`void on_error(error_listener const& l)`
42+
43+
Bind the error handler for socket.io error messages.
44+
45+
`void off_error()`
46+
47+
Unbind the error handler.
48+
49+
```C++
50+
//event object:
51+
class event
52+
{
53+
public:
54+
const std::string& get_nsp() const;
55+
56+
const std::string& get_name() const;
57+
58+
const message::ptr& get_message() const;
59+
60+
bool need_ack() const;
61+
62+
void put_ack_message(message::ptr const& ack_message);
63+
64+
message::ptr const& get_ack_message() const;
65+
...
66+
};
67+
//event listener declare:
68+
typedef std::function<void(const std::string& name,message::ptr const& message,bool need_ack, message::ptr& ack_message)> event_listener_aux;
69+
70+
typedef std::function<void(event& event)> event_listener;
71+
72+
typedef std::function<void(message::ptr const& message)> error_listener;
73+
74+
```
75+
76+
#### Connect and close socket
77+
`connect` will happen for existing `socket`s automatically when `client` have opened up the physical connection.
78+
79+
`socket` opened with connected `client` will connect to its namespace immediately.
80+
81+
`void close()`
82+
83+
Positively disconnect from namespace.
84+
85+
#### Get name of namespace
86+
`std::string const& get_namespace() const`
87+
88+
Get current namespace name which the client is inside.
89+
90+
### *Client*
91+
#### Constructors
92+
`client()` default constructor.
93+
94+
#### Connection Listeners
95+
`void set_open_listener(con_listener const& l)`
96+
97+
Call when websocket is open, especially means good connectivity.
98+
99+
`void set_fail_listener(con_listener const& l)`
100+
101+
Call when failed in connecting.
102+
103+
`void set_close_listener(close_listener const& l)`
104+
105+
Call when closed or drop. See `client::close_reason`
106+
107+
```C++
108+
//connection listener declare:
109+
enum close_reason
110+
{
111+
close_reason_normal,
112+
close_reason_drop
113+
};
114+
typedef std::function<void(void)> con_listener;
115+
116+
typedef std::function<void(close_reason const& reason)> close_listener;
117+
```
118+
#### Socket listeners
119+
`void set_socket_open_listener(socket_listener const& l)`
120+
121+
Set listener for socket connect event, called when any sockets being ready to send message.
122+
123+
`void set_socket_close_listener(socket_listener const& l)`
124+
125+
Set listener for socket close event, called when any sockets being closed, afterward, corresponding `socket` object will be cleared from client.
126+
127+
```C++
128+
//socket_listener declare:
129+
typedef std::function<void(std::string const& nsp)> socket_listener;
130+
```
131+
132+
#### Connect and Close
133+
`void connect(const std::string& uri)`
134+
135+
Connect to socket.io server, eg. `client.connect("ws://localhost:3000");`
136+
137+
`void close()`
138+
139+
Close the client, return immediately.
140+
141+
`void sync_close()`
142+
143+
Close the client, return until it is really closed.
144+
145+
`bool opened() const`
146+
147+
Check if client's connection is opened.
148+
149+
#### Transparent reconnecting
150+
`void set_reconnect_attempts(int attempts)`
151+
152+
Set max reconnect attempts, set to 0 to disable transparent reconnecting.
153+
154+
`void set_reconnect_delay(unsigned millis)`
155+
156+
Set minimum delay for reconnecting, this is the delay for 1st reconnecting attempt,
157+
then the delay duration grows by attempts made.
158+
159+
`void set_reconnect_delay_max(unsigned millis)`
160+
161+
Set maximum delay for reconnecting.
162+
163+
`void set_reconnecting_listener(con_listener const& l)`
164+
165+
Set listener for reconnecting is in process.
166+
167+
`void set_reconnect_listener(reconnect_listener const& l)`
168+
169+
Set listener for reconnecting event, called once a delayed connecting is scheduled.
170+
171+
#### Namespace
172+
`socket::ptr socket(std::string const& nsp)`
173+
174+
Get a pointer to a socket which is paired with the specified namespace.
175+
176+
#### Session ID
177+
`std::string const& get_sessionid() const`
178+
179+
Get socket.io session id.
180+
181+
### *Message*
182+
`message` Base class of all message object.
183+
184+
`int_message` message contains a 64-bit integer.
185+
186+
`double_message` message contains a double.
187+
188+
`string_message` message contains a string.
189+
190+
`array_message` message contains a `vector<message::ptr>`.
191+
192+
`object_message` message contains a `map<string,message::ptr>`.
193+
194+
`message::ptr` pointer to `message` object, it will be one of its derived classes, judge by `message.get_flag()`.
195+
196+
All designated constructor of `message` objects is hidden, you need to create message and get the `message::ptr` by `[derived]_message:create()`.

‎BOOST.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Boost setup
2+
3+
1. Download boost from [boost.org](http://www.boost.org/).
4+
1. Unpack boost to some place.
5+
1. Run either .\bootstrap.bat (on Windows), or ./bootstrap.sh (on other operating systems) under boost folder.
6+
7+
## Boost build (Build the necessary subset only)
8+
9+
#### Windows (or other mainstream desktop platforms shall work too):
10+
Run with following script will build the necessary subset:
11+
12+
```bash
13+
bjam install --prefix="<your boost install folder>" --with-system --with-date_time --with-random link=static runtime-link=shared threading=multi
14+
```
15+
Optionally You can merge all output .lib files into a fat one,especially if you're not using cmake.
16+
17+
In output folder, run:
18+
19+
```bash
20+
lib.exe /OUT:boost.lib *
21+
```

‎INSTALL.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## Install
2+
3+
### With CMake
4+
1. Install boost, see [Boost setup](#boost_setup) section.
5+
2. Use `git clone --recurse-submodules https://github.com/socketio/socket.io-client-cpp.git` to clone your local repo.
6+
3. Run `cmake -DBOOST_ROOT:STRING=<your boost install folder> -DBOOST_VER:STRING=<your boost version> ./`
7+
4. Run `make install`(if makefile generated) or open generated project (if project file generated) to build.
8+
5. Outputs is under `./build`, link with the all static libs under `./build/lib` and include headers under `./build/include` in your client code where you want to use it.
9+
10+
* If you're using boost without install,you can specify `boost include dir` and `boost lib dir` separately by:
11+
```bash
12+
cmake
13+
-DBOOST_INCLUDEDIR=<your boost include folder>
14+
-DBOOST_LIBRARYDIR=<your boost lib folder>
15+
-DBOOST_VER:STRING=<your boost version>
16+
./
17+
```
18+
* CMake didn't allow merging static libraries,but they're all copied to `./build/lib`, you can DIY if you like.
19+
20+
### Without CMake
21+
1. Install boost, see [Boost setup](#boost_setup) section.
22+
2. Use `git clone --recurse-submodules https://github.com/socketio/socket.io-client-cpp.git` to clone your local repo.
23+
3. Add `<your boost install folder>/include`,`./lib/websocketpp` and `./lib/rapidjson/include` to headers search path.
24+
4. Include all files under `./src` in your project, add `sio_client.cpp`,`sio_socket.cpp`,`internal/sio_client_impl.cpp`, `internal/sio_packet.cpp` to source list.
25+
5. Add `<your boost install folder>/lib` to library search path, add `boost.lib`(Win32) or `-lboost`(Other) link option.
26+
6. Include `sio_client.h` in your client code where you want to use it.
27+
28+
## Boost setup
29+
30+
1. Download boost from [boost.org](http://www.boost.org/).
31+
1. Unpack boost to some place.
32+
1. Run either .\bootstrap.bat (on Windows), or ./bootstrap.sh (on other operating systems) under boost folder.
33+
34+
## Boost build (Build the necessary subset only)
35+
Windows (or other mainstream desktop platforms shall work too):
36+
37+
The following script will build the necessary subset:
38+
39+
```bash
40+
bjam install --prefix="<your boost install folder>" --with-system --with-date_time --with-random link=static runtime-link=shared threading=multi
41+
```
42+
Optionally You can merge all output .lib files into a fat one, especially if you're not using cmake.
43+
44+
In output folder, run:
45+
46+
```bash
47+
lib.exe /OUT:boost.lib *
48+
```

‎INSTALL_IOS.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
## iOS
2+
3+
### Option 1: Cocoapods
4+
5+
```
6+
pod 'SocketIO-Client-CPP'
7+
```
8+
9+
### Option 2: Create a static library
10+
11+
1. Create a static library
12+
1. Copy the header files into xcode
13+
14+
Use the static libraries generated by the example project [iOS example project](examples/iOS)
15+
16+
Create one for
17+
- release iphoneos
18+
- release simulator
19+
- debug iphoneos
20+
- debug simulator
21+
22+
Join the debug libraries and the release libraries with e.g.
23+
```
24+
libtool -static -o libUniversalRelease.a Release-iphoneos/libsioclient.a Release-iphonesimulator/libsioclient.a
25+
libtool -static -o libUniversalDebug.a Debug-iphoneos/libsioclient.a Debug-iphonesimulator/libsioclient.a
26+
```
27+
28+
29+
### Option 3: Manual integration
30+
31+
Use this [shell](https://gist.github.com/melode11/a90114a2abf009ca22ea) to download and build boost completely automattically. It installs boost to `<shell folder>/prefix`.
32+
33+
See the [iOS example project](examples/iOS) for how to integrate the rest.

0 commit comments

Comments
 (0)