Learn how to evaluate and integrate the VNC SDK

We're here if you need help.

Messaging.h

Enables a Viewer and Server to send and receive messages over the same secure data channel as the current screen sharing session. (more...)

Data structures

Modifier and Type Name and Description
struct

vnc_MessagingManager_Callback

Callback notifying when messages are received.

Functions

Modifier and Type Name and Description
function vnc_status_t

vnc_MessagingManager_setCallback(vnc_MessagingManager *messagingManager, const vnc_MessagingManager_Callback *callback, void *userData)

Registers a callback notifying when messages are received.
function vnc_status_t

vnc_MessagingManager_sendMessage(vnc_MessagingManager *messagingManager, const void *buffer, int bufferLength, vnc_Connection *connection)

Sends a message.

Detailed description

Enables a Viewer and Server to send and receive messages over the same secure data channel as the current screen sharing session.

To enable a Viewer app to send and/or receive messages, call vnc_Viewer_getMessagingManager. To enable a Server app to send and/or receive messages, call vnc_Server_getMessagingManager. Both functions return a vnc_MessagingManager object.

Call vnc_MessagingManager_sendMessage to send a message. To be notified when a message is received, call vnc_MessagingManager_setCallback and monitor vnc_MessagingManager_Callback::messageReceived.

You can send up to 1MB of data per message, in any format (note the Python sample apps demonstrating this feature send JSON-RPC). The vnc_DataBuffer object received is owned by the SDK and destroyed as soon as the callback completes. You should take a copy of this data to interact with it, and do not call vnc_DataBuffer_destroy on the object.

If sending a message reports vnc_success, the message is guaranteed to be sent in sequence order. However, the sender is not informed by the underlying transport mechanism when it has been sent, and nor is it notified when a message has been received. You should send your own ACK packets to implement this behavior. If a disconnect occurs after vnc_MessagingManager_sendMessage is called and before the data has been sent there is a guarantee that the data will be dropped and a send will not be attempted on the reconnection.

If sending a message reports vnc_failure, no message will be sent. Partial messages are not sent.

Since
1.5

Functions

vnc_status_t vnc_MessagingManager_setCallback(vnc_MessagingManager *messagingManager, const vnc_MessagingManager_Callback *callback, void *userData)

Registers a callback notifying when messages are received.

You should call this function before your app attempts either to connect or to listen for connections.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Since
1.5
Parameters
  • messagingManager -

    Belonging to either a Viewer or a Server.

  • callback -

    The callback.

vnc_status_t vnc_MessagingManager_sendMessage(vnc_MessagingManager *messagingManager, const void *buffer, int bufferLength, vnc_Connection *connection)

Sends a message.

Return
vnc_success or vnc_failure, in which case call vnc_getLastError() to get the error code.
Since
1.5
Parameters
  • messagingManager -

    Belonging to either a Viewer or a Server.

  • buffer -

    The data to send.

  • bufferLength -

    The number of bytes. Maximum 1MB.

  • connection -

    For a Server, the Viewer to send the message to. To send to all Viewers, iterate over connections. For a Viewer, specify NULL.

Return Value
  • PeerNotSupported -

    The peer does not support receiving messages (perhaps no add-on code has been applied).

  • BufferFull -

    Too much data is being sent.

struct vnc_MessagingManager_Callback
#include <Messaging.h>

Callback notifying when messages are received.

See
vnc_MessagingManager_setCallback

Public Members

void(* vnc_MessagingManager_Callback::messageReceived) (void *userData, vnc_MessagingManager *messagingManager, vnc_Connection *sender, const vnc_DataBuffer *buffer)

Notification that a message has been received.

The vnc_Databuffer object containing the data is owned by the SDK and is automatically destroyed when the callback completes. Take a copy of the data to interact with it. Do not call vnc_DataBuffer_destroy.

Since
1.5
Parameters
  • messagingManager -

    Belonging to either a Viewer or a Server.

  • sender -

    The peer sending the message.

  • buffer -

    The data received.

×