diff --git a/API.md b/API.md index 1061fc74..e3b1b0f2 100644 --- a/API.md +++ b/API.md @@ -1,5 +1,5 @@ -## API -### *Overview* +# API +# *Overview* There're just 3 roles in this library - `socket`, `client` and `message`. `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. @@ -12,86 +12,11 @@ Use `socket` to send messages under namespace and receives messages in the names The `message` is just about the content you want to send, with text, binary or structured combinations. -### *Socket* -#### Constructors -Sockets are all managed by `client`, no public constructors. - -You can get it's pointer by `client.socket(namespace)`. - -#### Event Emitter -`void emit(std::string const& name, message::list const& msglist, std::function const& ack)` - -Universal event emition interface, by applying implicit conversion magic, it is backward compatible with all previous `emit` interfaces. - -#### Event Bindings -`void on(std::string const& event_name,event_listener const& func)` - -`void on(std::string const& event_name,event_listener_aux const& func)` - -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 convenience. - -`void off(std::string const& event_name)` - -Unbind the event callback with specified name. - -`void off_all()` - -Clear all event bindings (not including the error listener). - -`void on_error(error_listener const& l)` - -Bind the error handler for socket.io error messages. - -`void off_error()` - -Unbind the error handler. - -```C++ -//event object: -class event -{ -public: - const std::string& get_nsp() const; - - const std::string& get_name() const; - - const message::ptr& get_message() const; - - bool need_ack() const; - - void put_ack_message(message::ptr const& ack_message); - - message::ptr const& get_ack_message() const; - ... -}; -//event listener declare: -typedef std::function event_listener_aux; - -typedef std::function event_listener; - -typedef std::function error_listener; - -``` - -#### Connect and close socket -`connect` will happen for existing `socket`s automatically when `client` have opened up the physical connection. - -`socket` opened with connected `client` will connect to its namespace immediately. - -`void close()` - -Positively disconnect from namespace. - -#### Get name of namespace -`std::string const& get_namespace() const` - -Get current namespace name which the client is inside. - -### *Client* -#### Constructors +# *Client* +### Constructors `client()` default constructor. -#### Connection Listeners +### Connection Listeners `void set_open_listener(con_listener const& l)` Call when websocket is open, especially means good connectivity. @@ -115,7 +40,7 @@ typedef std::function con_listener; typedef std::function close_listener; ``` -#### Socket listeners +### Socket listeners `void set_socket_open_listener(socket_listener const& l)` Set listener for socket connect event, called when any sockets being ready to send message. @@ -129,7 +54,7 @@ Set listener for socket close event, called when any sockets being closed, after typedef std::function socket_listener; ``` -#### Connect and Close +### Connect and Close `void connect(const std::string& uri)` Connect to socket.io server, e.g., `client.connect("ws://localhost:3000");` @@ -146,7 +71,7 @@ Close the client, return until it is really closed. Check if client's connection is opened. -#### Transparent reconnecting +### Transparent reconnecting `void set_reconnect_attempts(int attempts)` Set max reconnect attempts, set to 0 to disable transparent reconnecting. @@ -168,17 +93,93 @@ Set listener for reconnecting is in process. Set listener for reconnecting event, called once a delayed connecting is scheduled. -#### Namespace +### Namespace `socket::ptr socket(std::string const& nsp)` Get a pointer to a socket which is paired with the specified namespace. -#### Session ID +### Session ID `std::string const& get_sessionid() const` Get socket.io session id. -### *Message* +# *Socket* +### Constructors +Sockets are all managed by `client`, no public constructors. + +You can get it's pointer by `client.socket(namespace)`. + +### Event Emitter +`void emit(std::string const& name, message::list const& msglist, std::function const& ack)` + +Universal event emition interface, by applying implicit conversion magic, it is backward compatible with all previous `emit` interfaces. + +### Event Bindings +`void on(std::string const& event_name,event_listener const& func)` + +`void on(std::string const& event_name,event_listener_aux const& func)` + +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 convenience. + +`void off(std::string const& event_name)` + +Unbind the event callback with specified name. + +`void off_all()` + +Clear all event bindings (not including the error listener). + +`void on_error(error_listener const& l)` + +Bind the error handler for socket.io error messages. + +`void off_error()` + +Unbind the error handler. + +```C++ +//event object: +class event +{ +public: + const std::string& get_nsp() const; + + const std::string& get_name() const; + + const message::ptr& get_message() const; + + bool need_ack() const; + + void put_ack_message(message::ptr const& ack_message); + + message::ptr const& get_ack_message() const; + ... +}; +//event listener declare: +typedef std::function event_listener_aux; + +typedef std::function event_listener; + +typedef std::function error_listener; + +``` + +### Connect and close socket +`connect` will happen for existing `socket`s automatically when `client` have opened up the physical connection. + +`socket` opened with connected `client` will connect to its namespace immediately. + +`void close()` + +Positively disconnect from namespace. + +### Get name of namespace +`std::string const& get_namespace() const` + +Get current namespace name which the client is inside. + + +# *Message* `message` Base class of all message object. `int_message` message contains a 64-bit integer.