Message Persistence API for PubNub C-Core SDK
Message Persistence provides real-time access to the history of all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds and is stored across multiple availability zones in several geographical locations. Stored messages can be encrypted with AES-256 message encryption, ensuring that they are not readable while stored on PubNub's network. For more information, refer to Message Persistence.
Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.
You can retrieve the following:
- Messages
- Message reactions
- File Sharing (using File Sharing API)
Fetch History
Requires Message Persistence
This method requires that Message Persistence is enabled for your key in the Admin Portal. Read the support page on enabling add-on features on your keys.
This function fetches historical messages from one or multiple channels. The include_message_actions
flag also allows you to fetch message reactions along with the messages.
It's possible to control how messages are returned and in what order.
- if you specify only the
start
parameter (withoutend
), you will receive messages that are older than thestart
timetoken - if you specify only the
end
parameter (withoutstart
), you will receive messages from thatend
timetoken and newer - if you specify values for both
start
andend
parameters, you will retrieve messages between those timetokens (inclusive of theend
value)
You will receive a maximum of 100 messages for a single channel or 25 messages for multiple channels (up to 500). If more messages meet the timetoken criteria, make iterative calls while adjusting the start
timetoken to fetch the entire list of messages from Message Persistence.
Method(s)
To fetch messages, use the following method(s) in the Objective-C SDK. This method uses the builder pattern; you can omit any optional arguments.
enum pubnub_res pubnub_fetch_history(
pubnub_t* pb,
char const* channel,
struct pubnub_fetch_history_options opt);
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | Yes | Pointer to PubNub client context. Can't be NULL. |
channel | const char* | Yes | The string with the channel name to fetch the history . |
opt → max_per_channel | unsigned int | Yes | Specifies the number of historical messages to return per channel. Maximum value is 100 for a single channel or 25 for multiple channels. |
opt → include_meta | pubnub_tribool | No | Whether event metadata should be included in response or not. |
opt → include_message_type | pubnub_tribool | No | Indicates whether to retrieve messages with PubNub message type. Default is YES . For more information, refer to Retrieving Messages. |
opt → include_custom_message_type | pubnub_tribool | No | Indicates whether to retrieve messages with the custom message type. For more information, refer to Retrieving Messages. |
opt → include_user_id | pubnub_tribool | No | Pass YES to receive the publisher uuid with each history message. Default is YES . |
opt → include_message_actions | pubnub_tribool | No | Whether event actions should be included in response or not. When YES , throws an exception if you call the method with more than one channel . |
opt → reverse | pubnub_tribool | No | Setting to YES traverses the time line in reverse, starting with the oldest message first. |
opt → start | char const* | No | Timetoken for oldest event starting from which next should be returned events. Value will be converted to required precision internally. |
opt → end | char const* | No | Timetoken for latest event till which events should be pulled out. Value will be converted to required precision internally. |
Basic Usage
struct pubnub_fetch_history_options options = pubnub_fetch_history_defopts();
options.include_custom_message_type = true;
// Fetch history and check whether operation started or not.
if (pubnub_fetch_history(ctx, "my_channel1,my_channel2", options) != PNR_IN_PROGRESS) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
return -1;
}
// Wait for `history` operation completion before trying to get a service response.
enum pubnub_res pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
return -1;
show all 18 linesResponse
This method returns a enum pubnub_res pbresult
on success:
enum pubnub_res pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
return -1;
}
pubnub_chamebl_t response = pubnub_get_fetch_history(ctx);
Other Examples
Fetch messages with metadata
struct pubnub_fetch_history_options options = pubnub_fetch_history_defopts();
options.include_meta = true;
// Fetch history and check whether operation started or not.
if (pubnub_fetch_history(ctx, "my_channel1,my_channel2", options) != PNR_IN_PROGRESS) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
return -1;
}
// Wait for `history` operation completion before trying to get a service response.
enum pubnub_res pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
show all 19 linesFetch messages with actions
struct pubnub_fetch_history_options options = pubnub_fetch_history_defopts();
options.include_message_actions = true;
// Fetch history and check whether operation started or not.
if (pubnub_fetch_history(ctx, "my_channel1,my_channel2", options) != PNR_IN_PROGRESS) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
return -1;
}
// Wait for `history` operation completion before trying to get a service response.
enum pubnub_res pbresult = pubnub_await(ctx);
if (pbresult != PNR_OK) {
printf("Failed to fetch history, error %d\n", pbresult);
pubnub_free(ctx);
show all 19 linesHistory
This function fetches historical messages of a channel. Message Persistence provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub's network. It is possible to control how messages are returned and in what order, for example you can:
- Limit the number of messages to a specific quantity using the
4th argument
parameter.
Method(s)
To run History
you can use the following method(s) in the C-Core SDK:
enum pubnub_res pubnub_history (
pubnub_t *p,
const char *channel,
const char *channel_group,
unsigned count
)
Parameter | Type | Required | Description |
---|---|---|---|
p | pubnub_t* | Yes | Pointer to PubNub client context. Can't be NULL. |
channel | const char* | Yes | The string with the channel name to fetch the history |
count | unsigned | Yes | Maximum number of messages to get. If there are less than this available on the channel , you'll get less, but you can't get more. |
include_token | bool | Yes | If true , include the timetoken for every message . default: false |
Basic Usage
Retrieve the last 100 messages on a channel:
// Sync
enum pubnub_res res;
pubnub_history(pn, "history_channel", 10, false);
res = pubnub_await(pn);
if (PNR_OK == res) {
puts("Got history! Messages:");
for (;;) {
const char *msg = pubnub_get(pn);
if (NULL == msg) {
break;
}
puts(msg);
}
show all 42 linesRest Response from Server
An array is returned on success.
The pubnub_history()
function returns a list of up to 100 messages, the timetoken of the first (oldest) message and the timetoken of the last (newest) message in the resulting set of messages. The output below demonstrates the format for a pubnub_history()
response:
[
["message1", "message2", "message3",... ],
"Start Time Token",
"End Time Token"
]
Extended History
Extended History Options structure
Options for extended
history.
Method(s)
Declaration
struct pubnub_history_options {
bool string_token;
int count;
bool reverse;
char const* start;
char const* end;
bool include_token;
}
Members
Member | Type | Description |
---|---|---|
string_token | bool | If false , the returned start and end Timetoken values will be returned as long ints. If true , the start and end Timetoken values will be returned as strings. Default is false . |
count | int | The maximum number of messages to return per response. Has to be between 1 and 100 messages. Default is 100. |
reverse | bool | Direction of time traversal. Default is false, which means timeline is traversed newest to oldest. |
start | char const* | If provided (not NULL), lets you select a "start date," in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end timetoken. Retrieve a slice of the time line by providing both a start AND end timetoken. start is exclusive – that is, the first item returned will be the one immediately after the start Timetoken value. Default is NULL . |
end | char const* | If provided (not NULL), lets you select an "end date," in Timetoken format. If not provided, it will provide up to the number of messages defined in the "count" parameter. Page through results by providing a start OR end timetoken. Retrieve a slice of the time line by providing both a start AND end timetoken. End is exclusive – that is, if a message is associated exactly with the end Timetoken , it will be included in the result. Default is NULL . |
include_token | bool | Pass true to receive a timetoken with each history message. Defaults to false . |
Initialize extended History options
This returns the default
options for publish V1 transactions. It's best to always call it to initialize the pubnub_history_options()
, since it has several parameters.
Method(s)
Declaration
struct pubnub_history_options pubnub_history_defopts(void)
Parameters
This Method has no arguments.
Basic Usage
struct pubnub_history_options opts = pubnub_history_defopts();
Returns
Type | Value | Description |
---|---|---|
struct pubnub_history_options | The default options for here-now. |
Extended History
The extended history
. It is basically the same as the pubnub_history()
, just adding a few options that will be sent.
Method(s)
Declaration
enum pubnub_res pubnub_history_ex(
pubnub_t* pb,
char const* channel,
struct pubnub_history_options opt
)
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | yes | The Pubnub context |
channel | char const* | yes | The string with the channel name to get history for. |
opt | struct pubnub_history_options | yes | History options. |
Basic Usage
struct pubnub_history_options opt = pubnub_history_defopts();
opt.reverse = true;
pbresult = pubnub_history_ex(pn, "my_channel", opt);
Returns
Type | Value | Description |
---|---|---|
enum pubnub_res | PNR_STARTED | Success. |
other | Indicates the type of error. |
Message Counts
Message count per channel structure
Contains channel name (as char memory block, aka Pascal string
) and message count for messages received on the channel. The message counts are the number of messages published on one or more channels since a given time.
Used to store information retrieved by pubnub_message_counts()
transaction.
Declaration
struct pubnub_chan_msg_count {
pubnub_chamebl_t channel;
size_t message_count;
}
Members
Members | Type | Description |
---|---|---|
channel | pubnub_chamebl_t | Channel name as a char memory block (aka Pascal string ) |
message_count | size_t | Number of messages for the channel |
Count channels in message count response
Returns the number of members (key->value pairs) of JSON object channels
in the response to a message count
transaction.
Declaration
int pubnub_get_chan_msg_counts_size(pubnub_t* pb)
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | Yes | The Pubnub context in which to parse the response |
Basic Usage
int n = pubnub_get_chan_msg_counts_size(pb);
printf("There are %d channels in the message counts response\n", n);
Returns
Type | Value | Description |
---|---|---|
int | -1 | Error (transaction still in progress or other) |
>= 0 | The number of members of the channels JSON object) |
Message Counts transaction
Starts the transaction pubnub_message_counts
on the context @p
pb for the list of channels @p
channel for messages counts starting from @p
timeoken which can be a single timetoken, or list of comma-separated timetokens (corresponding to the channel
list).
Unlimited message retention
For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.
Declaration
enum pubnub_res pubnub_message_counts(
pubnub_t* pb,
char const* channel,
char const* timetoken
)
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | Yes | The Pubnub context to use for transaction |
channel | char const* | Yes | The string with the channel name (or comma-delimited list of channel names) to subscribe for. |
timetoken | char const* | Yes | A single token OR a comma-separated list of tokens. If single, will be used for all channels. If a list, has to have the same number of elements as @p channel and each will be used for its channel, in-order. |
Basic Usage
/** Obtain message count for
channel 'one' since 15517035062228243 and
channel 'two' since 15517035052228243. */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243,15517035052228243");
Returns
Type | Value | Description |
---|---|---|
enum pubnub_res | PNR_STARTED | Started |
PNR_OK | Finished with a success (can only happen in the sync interface) | |
other | Failed, Indicates the type of error |
Example: Single token for all channels
/** Obtain message count for channels
'one' and 'two' since 15517035062228243 */
pbres = pubnub_message_counts(pb, "one,two", "15517035062228243");
Read all channel message counts
On input, @p
io_count
is the number of allocated counters per channel
(array dimension of @p
chan_msg_counters
). On output(@p
io_count
), number of counters per channel written. If there are more channel message counters in the answer than there are in the allocated array (can't fit all
), that will not be considered an error, they will simply not be written to @p
chan_msg_counters
. To see how much elements there are (and allocate accordingly), use pubnub_get_chan_msg_counts_size()
.
This is an alternative to pubnub_get_message_counts()
, useful for exploratory
usage, as one can get all the channel message counters that are in the report, without keeping track of what were the requested channels.
Unlimited retention
For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.
Declaration
int pubnub_get_chan_msg_counts(
pubnub_t* pb,
size_t* io_count,
struct pubnub_chan_msg_count* chan_msg_counters
)
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | Yes | The Pubnub context to use for transaction |
io_count | size_t* | Yes | On input, the number of allocated counters per channel (array dimension of @p chan_msg_counters ). On output, number of counters per channel written to @p chan_msg_counters . |
chan_msg_counters | struct pubnub_chan_msg_count* | Yes | An array of channel message counters, allocated by the caller, filled in by this function. |
Basic Usage
struct pubnub_chan_msg_count chan_msg_count[CHAN_COUNT];
size_t count = CHAN_COUNT;
int rslt = pubnub_get_chan_msg_counts(pb, &count, chan_msg_count);
if (0 == rslt) {
size_t i;
for (i = 0; i < count; ++i) {
printf(" Channel = '%.*s'\n", (int)chan_msg_count[i].channel.size, chan_msg_count[i].channel.ptr);
printf(" Message count = %z'\n", chan_msg_count[i].message_count);
}
}
Returns
Type | Value | Description |
---|---|---|
int | 0 | Success (even if there are more channel message counts than is possible to write to @p chan_msg_counters ) |
-1 | Error, messages not read (transaction still in progress, format error...) |
Example: Make sure we have room for all the channel message counters
int n = pubnub_get_chan_msg_counts_size(pb);
if (n > 0) {
struct pubnub_chan_msg_count *pchmsc = malloc(n * sizeof *pchmsc);
if (pchmsc != NULL) {
size_t count = n;
int rslt = pubnub_get_chan_msg_counts(pb, &count, pchmsc);
if (0 == rslt) {
printf("Got %z counters, should be the same as %d\n", count, n);
}
free(pchmsc);
}
}
Read counters for channels
Reads message counters for the given channels (in @p
channel) from the PubNub response to pubnub_message_counts()
.
Array dimension for @p
o_count
is the number of channels from the comma-separated channel list @p
channel and it (@p
o_count
array) is allocated by the caller.
Message counts order in @p
o_count
is corresponding to channel order in @p
channel list respectively, even if the answer itself has the channels in a different order. If a requested channel is not found in the PubNub response, the message counter in the respective @p
o_count
array member has a negative value.
If there is a channel name in the answer, not to be found in requested @p
channel list, that is not considered an error.
This is an alternative to pubnub_get_chan_msg_count()
, useful if we already maintain
the list of channels and just want to get the message counters.
Unlimited message retention
For keys with unlimited message retention enabled, this transaction considers only messages published in the last 30 days.
Declaration
int pubnub_get_message_counts(
pubnub_t* pb,
char const*channel,
int* o_count
)
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
pb | pubnub_t* | Yes | The Pubnub context to use for transaction |
channel | char const* | Yes | A comma-separated list of channels to read message counters from |
o_count | int* | Yes | An array of message counters, allocated by the caller, filled in by this function. |
Basic Usage
int msg_count[2];
int rslt = pubnub_get_message_counts(pb, "one,two", msg_count);
if (0 == rslt) {
printf("message counts: one -> %d, two -> %d\n", msg_count[0], msg_count[1]);
}
Returns
Type | Value | Description |
---|---|---|
int | 0 | Success (even if there are channel message counts int @p channel that are not there in the response or vice-versa) |
-1 | Error, messages not read (transaction still in progress, format error...) |