Sending messages

A client can send a message to a message path without specifying any further details about the intended recipient. In this case, Diffusion® Cloud will route the message to one client that has registered a handler matching the message path.

If multiple clients have handlers matching the path, the message will be delivered to one of them at random.

Sending to a specific session

You can send a request message to a specific client session, using its session ID. The receiving client still needs to have a handler that is registered to the same message path.

Java and Android
final JSON request = Diffusion.dataTypes()
    .json().fromJsonString("{\"hello\": \"world\"}");
final JSON response = session.feature(Messaging.class)
    .sendRequest(sessionId, messagePath, request, JSON.class, JSON.class).get();
LOG.info("Received response: " + response.toJsonString());
JavaScript
const jsonDataType = diffusion.datatypes.json();
const jsonValue = jsonDataType.from({
    hello : 'world'
});

const response = await session.messages.sendRequest(message_path, jsonValue, session_id, jsonDataType);
.NET
var jsonRequest = Diffusion.DataTypes.JSON.FromJSONString("{\"hello\": \"world\"}");

IJSON response = await session.Messaging.SendRequestAsync<IJSON, IJSON>(
    sessionId, messagePath, jsonRequest);
WriteLine($"Received response: {response.ToJSONString()}.");
C
static int on_response(
        DIFFUSION_DATATYPE response_datatype,
        const DIFFUSION_VALUE_T *response,
        void *context)
{
        DIFFUSION_API_ERROR api_error;
        char *response_json_string;
        bool success = to_diffusion_json_string(response, &response_json_string, &api_error);
        if (success) {
                printf("Received response: %s\n\n", response_json_string);
                free(response_json_string);
        }
        return HANDLER_SUCCESS;
}


...


BUF_T *value_buf = buf_create();
write_diffusion_json_value("{\"hello\": \"world\"}", value_buf);

SEND_REQUEST_TO_SESSION_PARAMS_T parameters = {
        .recipient_session = session_id,
        .path = message_path,
        .request = value_buf,
        .request_datatype = DATATYPE_JSON,
        .response_datatype = DATATYPE_JSON,
        .on_response = on_response
};

send_request_to_session(session, parameters);
Python
response = await session.messaging.send_request_to_session(
    path=message_path,
    session_id=session_id,
    request=diffusion.datatypes.JSON({"hello": "world"})
)
print(f"Received response: {response}")
Apple
let json_request = try! PTDiffusionJSON(jsonString: "{\"hello\": \"world\"}").request

session.messaging.send(
    json_request,
    to: session_id,
    path: message_path,
    jsonCompletionHandler: { (response: PTDiffusionJSON?, error) in
        print("Received response: %@", response!)
    })

Sending to a group of sessions

Using a message path

You can send a message to a group of clients via a message path only.
The Diffusion® Cloud Server will send the message to every client that have a registered request handler that matches the message path.

Java and Android
final JSON request = Diffusion.dataTypes()
    .json().fromJsonString("{\"hello\": \"world\"}");
session.feature(Messaging.class)
.sendRequest(messagePath, request, JSON.class, JSON.class);
JavaScript
const jsonDataType = diffusion.datatypes.json();
const jsonValue = jsonDataType.from({
    hello : 'world'
});

session.messages.sendRequest(message_path, jsonValue, jsonDataType);
.NET
var jsonRequest = Diffusion.DataTypes.JSON.FromJSONString("{\"hello\": \"world\"}");

IJSON response = await session.Messaging.SendRequestAsync<IJSON, IJSON>(
    messagePath, jsonRequest);
WriteLine($"Received response: {response.ToJSONString()}.");
C
BUF_T *value_buf = buf_create();
write_diffusion_json_value("{\"hello\": \"world\"}", value_buf);

SEND_REQUEST_PARAMS_T parameters = {
        .path = message_path,
        .request = value_buf,
        .request_datatype = DATATYPE_JSON,
        .response_datatype = DATATYPE_JSON,
        .on_response = on_response
};

send_request(session, parameters);
Python
response = await session.messaging.send_request_to_path(
    path=message_path,
    request=diffusion.datatypes.JSON({"hello": "world"})
)
print(f"Received response: {response}")
Apple
let json_request = try! PTDiffusionJSON(jsonString: "{\"hello\": \"world\"}").request

session.messaging.send(json_request, toPath: message_path) { (response: PTDiffusionJSON?, error) in
    print("Received response: %@", response!)
}

Using a session filter

You can send a message to a group of clients matching a session filter. The Diffusion® Cloud Server sends the message to every client session with session properties that match the filter.
Only clients with a message request handler matching the message path will receive the message.

Java and Android
final JSON request = Diffusion.dataTypes()
    .json().fromJsonString("{\"hello\": \"world\"}");
final int numberOfResponses = session.feature(Messaging.class).sendRequestToFilter(
    sessionPropertiesFilter, messagePath, request, JSON.class, JSON.class,
    new Messaging.FilteredRequestCallback<JSON>() {
        @Override
        public void onResponse(SessionId sessionId, JSON response) {
            LOG.info("on response: " + response);
        }
        @Override
        public void onResponseError(SessionId sessionId, Throwable throwable) {
            LOG.info("on error: " + throwable.getMessage());
        }
        }).get();

LOG.info("Requests sent: " + numberOfResponses);
JavaScript
// create the request
const jsonDataType = diffusion.datatypes.json();
const jsonValue = jsonDataType.from({
    hello : 'world'
});

// send the message request
session.messages.sendRequestToFilter(
    session_properties_filter,
    message_path,
    jsonValue,
    filtered_response_handler
);
.NET
private class JSONSessionResponseHandler : IFilteredRequestCallback<IJSON>
{
    public void OnResponse(ISessionId sessionId, IJSON json)
        => WriteLine($"Received response from {sessionId}: {json.ToJSONString()}.");

    public void OnResponseError(ISessionId sessionId, Exception error)
        => WriteLine($"Received error from {sessionId}: {error}.");
}

...

// Create the request.
var jsonRequest = Diffusion.DataTypes.JSON.FromJSONString("{\"hello\": \"world\"}");

// Create the handler that will receive the responses.
var handler = new JSONSessionResponseHandler();

// Send the message request.
int selectedSessions = await session.Messaging.SendRequestToFilterAsync(sessionPropertiesFilter, messagingPath, jsonRequest, handler);
WriteLine($"Message successfully sent to {selectedSessions} sessions.");
C
static int on_number_sent(int number_sent, void *context)
{
        printf("Requests sent: %d\n", number_sent);
        return HANDLER_SUCCESS;
}


...


BUF_T *value_buf = buf_create();
write_diffusion_json_value("{\"hello\": \"world\"}", value_buf);

SEND_REQUEST_TO_FILTER_PARAMS_T parameters = {
        .path = message_path,
        .filter = session_properties_filter,
        .request_datatype = DATATYPE_JSON,
        .response_datatype = DATATYPE_JSON,
        .on_response = on_response,
        .on_number_sent = on_number_sent,
        .request = value_buf,
};

send_request_to_filter(session, parameters);
Python
affected_sessions = await session.messaging.send_request_to_filter(
    session_filter=session_properties_filter,
    path=message_path,
    request=diffusion.datatypes.JSON({"hello": "world"}),
)
print(f"Message successfully sent to {affected_sessions} sessions.")
Apple
class JSONSessionResponseHandler: PTDiffusionJSONSessionResponseStreamDelegate {
    func diffusionStream(_ stream: PTDiffusionStream,
                         didReceiveResponseWith json: PTDiffusionJSON,
                         from sessionId: PTDiffusionSessionId) {
        print("Received response from %@: %@", sessionId, json)
    }

    func diffusionStream(_ stream: PTDiffusionStream,
                         didReceiveError error: Error,
                         from sessionId: PTDiffusionSessionId) {
        print("Received error from %@: %@", sessionId, error)
    }

    func diffusionStream(_ stream: PTDiffusionStream,
                         didFailWithError error: Error) {
        print("Stream failed with error: %@", error.localizedDescription)
    }

    func diffusionDidClose(_ stream: PTDiffusionStream) {
        print("Stream is now closed")
    }
}

...

// create the request
let json_request = try! PTDiffusionJSON(jsonString: "{\"hello\": \"world\"}").request

// create the handler that will receive the responses
let handler = JSONSessionResponseHandler()
let response_stream = PTDiffusionJSON.sessionResponseStream(with: handler)

// send the message request
session.messaging.send(
    json_request,
    toFilter: session_properties_filter,
    path: message_path,
    responseStream: response_stream) { (selectedSessions, error) in
        print("Message successfully sent to %lu sessions", selectedSessions)
}