Message

Go back to API Reference

Websockets communication is made of Messages constructed and transmitted as Fragments. In TinyWebsockets, the WebsocketsMessage class is used to represent either a Frame or a complete Message received by the client.

WebsocketsMessage

Table Of Contents

1. Payload
2. Types
3. Fragmented Messages
4. Validation
5. Examples

Payload

To acccess the message's data, use:

std::string data() const;

A message may have no payload or a binary content in it's data field.

---

Types

Websockets Messages have types indicated by the opcode they were sent with.

Messages have a MessageType member to indicate their type. MessageType is declared as follows:

enum class MessageType {
  // Default (Error) value
  Empty,
  
  // Data Messages
  Text, Binary,

  // Control Messages
  Ping, Pong, Close
};

The following methods can help you determine the message's type:

Data Types

bool isText() const;
bool isBinary() const;

Control Types

bool isPing() const;
bool isPong() const;
bool isClose() const;

---

Fragmented Messages

In Websockets, a message can be fragmented to smaller individual Frames. In TinyWebsockets such partial messages (or frames) are also served as WebsocketsMessage object.

Check if a message is part of a stream (is it a fragmented frame) by using:

// is a message partial
bool isPartial() const;

In order to indicate the begining and end of streams, there are helper methods to check the "role" of the message in the stream:

bool isFirst() const; // true for the first message in a stream
bool isContinuation() const; // true for every message in the stream except the first and last
bool isLast() const; // true for the last message in a stream

MessageRole role() const; // accessor to the `role` member

MessageRole is defined as follows:

enum class MessageRole {
  // Normal, un-Fragmented message
  Complete, 

  First, // First message in a stream
  Continuation, // Middle messages in a stream
  Last // // Last message in a stream
};

Note:: By default, TinyWebsockets will aggregate partial messages for you and only notify you when the message is complete. Because of that, there is no need to check if a message is a continuation if you didn't enable any features for fragmented messages.

---

Validation

Sometimes there will be a need to return an empty message. An empty message is a message that represents an error while generating the object.

For example, a method that returns a WebsocketsMessage object may return an empty message to indicate error.

Important: a message with no payload is not empty!

Note: callbacks will never be called by TinyWebsockets with an empty message.

// check if a message is empty and should be ignored
bool isEmpty() const;

Examples

Basic Usage

// This function checks if a message is a text message with 
// the content "Hello World" 
bool isHelloWorld(websockets::WebsocketsMessage& msg) {
  if(msg.isText()) {
    return msg.data() == "Hello World";
  } else {
    return false;
  }
}

Handling Streams

// This function checks if a message is a text message with 
// the content "Hello World" 
void logMessage(websockets::WebsocketsMessage& msg) {
  if(msg.isComplete()) {
    std::cout << "Message is Complete." << std::endl;
  } else {
    std::cout << "Message is Partial, It is at the: ";
    if(msg.isFirst()) std::cout << "Begining" << std::endl;
    else if(msg.isContinuation()) std::cout << "Middle" << std::endl;
    else if(msg.isLast()) std::cout << "End" << std::endl;
  }
}

Go back to API Reference