On this page

File Sharing API for C SDK

File sharing lets you upload a file to a channel and notify subscribers that it is available, without building your own storage integration. Every function on this page is declared in #include <pubnub/features/files.h> and gated by PUBNUB_ENABLE_FILES.

Like every other feature entry point in this SDK, each function that performs network I/O returns a pubnub_future_t by value. Consume it with any of the three styles described in Calling patterns: cooperative polling, blocking pubnub_await, or callback via pubnub_async. pubnub_get_file_url() is the one exception: it does no network I/O and returns a plain pubnub_res_t directly.

pubnub_send_file() deserves a closer look before you use it: it is not one HTTP request, but three, chained behind a single future and a single request-pool slot. Send file below explains what that means for error handling, and in particular what to do when the upload succeeds but the notification does not.

Two feature flags, two different scopes

PUBNUB_ENABLE_FILES gates every function and struct on this page except the subscribe-side file event described in Receive file share events, which is gated by PUBNUB_ENABLE_SUBSCRIBE instead. A build with subscribe enabled and Files disabled still compiles that extractor.

PUBNUB_ENABLE_FILESYSTEM gates the platform provider's file_load member identically on POSIX, Windows, and FreeRTOS: when it's OFF, file_load is NULL on all three, and file_path support in pubnub_send_file_opts_t returns PUBNUB_ERR_NOT_SUPPORTED; when it's ON, file_load is wired on all three. There is no asymmetry among those three. The full profile turns this flag ON; minimal and embedded turn it OFF (moot for minimal/embedded in practice, since both also disable PUBNUB_ENABLE_FILES itself). The Zephyr platform provider is the one exception: it sets file_load = NULL unconditionally, regardless of PUBNUB_ENABLE_FILESYSTEM, so file_path support never compiles in on Zephyr today. Sending from an in-memory buffer (data/data_len, with file_path left NULL) is unaffected by this flag on every platform, including Zephyr. It's the portable choice on a filesystem-less target.

Send file

Upload the file to a specified channel.

This method covers the entire process of sending a file, including preparation, uploading the file to a cloud storage service, and post-uploading messaging on a channel.

For the last messaging step, pubnub_send_file internally calls the pubnub_publish_file_message method to publish a message on the channel.

The published message contains metadata about the file, such as the file identifier and name, enabling others on the channel to find out about the file and access it.

Method(s)

pubnub_future_t pubnub_send_file(pubnub_context_t* ctx, const pubnub_send_file_opts_t* opts);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_name` Type: `const char*` Default: —	Borrowed, NUL-terminated. The server may assign a different final name.
`data` Type: `const uint8_t*` Default: —	Borrowed. Must remain valid until `pubnub_future_is_ready()` returns non-zero.
`data_len` Type: `size_t` Default: —	Byte count of `data`.
`content_type` Type: `const char*` Default: `NULL` → `"application/octet-stream"`	Borrowed, NUL-terminated.
`message` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated. Must be valid JSON. Encrypted separately from the file content itself when a `crypto_module` is configured. See Encryption.
`meta` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated.
`custom_message_type` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated, 3-50 characters.
`store` Type: `int` Default: `1` (store)	Whether to store the published file message in history.
`ttl` Type: `unsigned int` Default: `0` (account default)	Minutes to retain the file message.
`upload_timeout_ms` Type: `uint32_t` Default: `0` → `300000` ms	Timeout for the storage-upload step only.
`timeout_ms` Type: `uint32_t` Default: `0` → `pubnub_config_t.transaction_timeout_ms`	Applies to the generate-upload-url and publish steps; not to the storage upload.
`file_path` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated. Read via the platform provider's `file_load`; see the feature-flag note above.

Exactly one of file_name and file_path must be set. If file_path is set and file_name is not, the SDK derives file_name from the path's basename. Supplying data with a non-zero data_len but no data pointer and no file_path is PUBNUB_ERR_INVALID_ARGUMENT.

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_send_file_opts_t, pubnub_send_file_result_t
Prerequisite — an initialized context with publish_key and subscribe_key set
Feature flag — PUBNUB_ENABLE_FILES
Ownership / lifetime — data is borrowed and must stay valid until the future is ready; id/name in the result alias memory owned by the future and are valid only until pubnub_future_release
Buffers — no client-side file-size limit; the server enforces a maximum (the header's own comment says "typically 5 MB," not a guaranteed number) and classifies an oversized upload as PUBNUB_ERR_INVALID_ARGUMENT
Blocking — never blocks; returns a pubnub_future_t immediately, though the operation it starts runs up to three sequential HTTP requests before that future becomes ready

One future, three HTTP requests, one request-pool slot

pubnub_send_file() does not return once the file reaches storage. It drives all three steps itself, internally, and only completes the future at the end:

Generate an upload URL. A request to PubNub for a presigned storage URL and a server-assigned file id.
Upload to storage. The file content, encrypted first if a crypto_module is configured on the context, is uploaded directly to the presigned URL.
Publish the file message. A message announcing id and name (plus your optional message/meta) is published to channel. This is the same thing Publish file message does on its own.

All three steps reuse the same request-pool slot. You never see or drive them individually, and pubnub_process() (or pubnub_await, or the async callback) is all you call regardless of which step is in flight. What matters operationally is what happens when step 2 or step 3 fails on its own, covered next.

A failed publish step still means the file exists. Do not call pubnub_send_file() again.

If step 2 (the storage upload) fails, that failure is terminal for this attempt. The presigned URL from step 1 is not reusable, there is no automatic retry, and the future completes with an error. pubnub_send_file_result() returns a zero-initialized result. Call pubnub_send_file() again from scratch. Nothing was created server-side.

If step 2 succeeds but step 3 (the publish) fails, the outcome is different: this is the case that's easy to get wrong. The future still completes with an error, but pubnub_send_file_result() returns a non-NULL id and name. The file is already stored. Only the announcement failed.

Calling pubnub_send_file() again in that case re-uploads the same content under a brand new id, leaving the original file orphaned in storage. Instead, read id/name from the failed result and call pubnub_publish_file_message() with them to finish the job without re-uploading. See Recover from a publish failure without re-uploading below.

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>
#include <pubnub/response.h>


#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.publish_key   = "demo";
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    static const char content[] = "Hello PubNub Files!";


    pubnub_send_file_opts_t opts = PUBNUB_SEND_FILE_OPTS_INIT;
    opts.channel      = "my_channel";
    opts.file_name    = "greeting.txt";
    opts.data         = (const uint8_t*)content;
    opts.data_len     = strlen(content);
    opts.content_type = "text/plain";


    pubnub_future_t future = pubnub_send_file(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        pubnub_send_file_result_t r = pubnub_send_file_result(future);
        printf("id: %.*s, name: %.*s, timetoken: %.*s\n",
               (int)r.id.len, r.id.ptr,
               (int)r.name.len, r.name.ptr,
               (int)r.timetoken.len, r.timetoken.ptr);
    }
    else {
        pubnub_string_view_t err = pubnub_response_error_message(future);
        printf("send_file failed: %.*s\n", (int)err.len, err.ptr);
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 52 lines

Adapted from examples/files/send_file.c (cooperative polling). This example takes the happy path only. See Recover from a publish failure without re-uploading for the partial-failure case.

Returns

pubnub_send_file_result_t pubnub_send_file_result(pubnub_future_t future);

pubnub_send_file_result_t has 3 fields:

Field	Type	Description
`id`	`pubnub_string_view_t`	Server-assigned file identifier. Populated on complete success and on the publish-failed partial case described above; zero-initialized (`id.ptr == NULL`) for every earlier failure.
`name`	`pubnub_string_view_t`	Stored file name. Follows the same populated/zero rule as `id`.
`timetoken`	`pubnub_timetoken_t`	Publish timetoken. Valid only when all three steps succeed.

Every view aliases memory owned by the future and is valid only until pubnub_future_release.

Use id.ptr together with pubnub_future_status() to tell the two failure cases apart:

`pubnub_future_status()`	`id.ptr`	What happened	Recovery
`PUBNUB_OK`	non-`NULL`	All three steps succeeded.	—
error	`NULL`	Failed generating the upload URL, or the storage upload itself failed. Nothing was created server-side, or the terminal upload failure discarded what was created.	Retry `pubnub_send_file()` from scratch.
error	non-`NULL`	Storage upload succeeded; publishing the file message failed.	Call `pubnub_publish_file_message()` with `id`/`name`. Do not call `pubnub_send_file()` again.

Other examples

Recover from a publish failure without re-uploading

This combines the two functions from the table above into one recovery path. Try the composed send. If it fails with id/name still populated, finish the job with pubnub_publish_file_message() instead of re-sending the file.

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>
#include <pubnub/response.h>


#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


static int publish_recovered_file_message(pubnub_context_t* ctx,
                                           const char*        channel,
                                           const char*        file_id,
                                           const char*        file_name)
{
    pubnub_publish_file_message_opts_t opts = PUBNUB_PUBLISH_FILE_MESSAGE_OPTS_INIT;
    opts.channel   = channel;
    opts.file_id   = file_id;
    opts.file_name = file_name;


    pubnub_future_t future = pubnub_publish_file_message(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    const pubnub_res_t status = pubnub_future_status(future);
    if (PUBNUB_OK == status) {
        pubnub_publish_file_message_result_t r = pubnub_publish_file_message_result(future);
        printf("recovered: published at %.*s\n", (int)r.timetoken.len, r.timetoken.ptr);
    }
    else {
        printf("recovery publish also failed; retry pubnub_publish_file_message later\n");
    }


    pubnub_future_release(future);
    return PUBNUB_OK == status ? 0 : 1;
}


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.publish_key   = "demo";
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    static const char content[]   = "Hello PubNub Files!";
    static const char channel[]   = "my_channel";


    pubnub_send_file_opts_t opts = PUBNUB_SEND_FILE_OPTS_INIT;
    opts.channel      = channel;
    opts.file_name    = "greeting.txt";
    opts.data         = (const uint8_t*)content;
    opts.data_len     = strlen(content);
    opts.content_type = "text/plain";


    pubnub_future_t future = pubnub_send_file(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    const pubnub_res_t     status = pubnub_future_status(future);
    pubnub_send_file_result_t result = pubnub_send_file_result(future);


    int rc = 0;
    if (PUBNUB_OK == status) {
        printf("sent: id=%.*s name=%.*s\n",
               (int)result.id.len, result.id.ptr,
               (int)result.name.len, result.name.ptr);
        pubnub_future_release(future);
    }
    else if (NULL != result.id.ptr) {
        /* Upload succeeded, only the publish step failed. Copy id/name out
           before releasing the future -- the views alias data owned by it. */
        char id_buf[64];
        char name_buf[256];
        size_t id_len   = result.id.len   < sizeof(id_buf) - 1   ? result.id.len   : sizeof(id_buf) - 1;
        size_t name_len = result.name.len < sizeof(name_buf) - 1 ? result.name.len : sizeof(name_buf) - 1;
        memcpy(id_buf, result.id.ptr, id_len);
        id_buf[id_len] = '\0';
        memcpy(name_buf, result.name.ptr, name_len);
        name_buf[name_len] = '\0';


        pubnub_future_release(future);


        /* Do NOT call pubnub_send_file() again here -- that would upload
           the content a second time. Finish delivery from what already
           exists in storage instead. */
        rc = publish_recovered_file_message(ctx, channel, id_buf, name_buf);
    }
    else {
        /* id.ptr == NULL: nothing was created. Safe to retry pubnub_send_file() from scratch. */
        printf("send_file failed before upload completed; retry pubnub_send_file() from scratch\n");
        pubnub_future_release(future);
        rc = 1;
    }


    pubnub_destroy(ctx);
    return rc == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
}
show all 104 lines

This combined flow builds on the pubnub_send_file/pubnub_publish_file_message signatures and result structs described above.

Send file asynchronously

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>
#include <pubnub/response.h>


#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


static volatile int s_done;


static void on_send_complete(pubnub_future_t future, pubnub_res_t status, void* user_data)
{
    (void)user_data;


    if (PUBNUB_OK == status) {
        pubnub_send_file_result_t r = pubnub_send_file_result(future);
        printf("sent: id=%.*s name=%.*s\n",
               (int)r.id.len, r.id.ptr,
               (int)r.name.len, r.name.ptr);
    }
    else {
        pubnub_string_view_t err = pubnub_response_error_message(future);
        printf("send_file failed: %.*s\n", (int)err.len, err.ptr);
    }


    pubnub_future_release(future);
    s_done = 1;
}


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.publish_key   = "demo";
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    static const char content[] = "Hello PubNub Files (async)!";


    pubnub_send_file_opts_t opts = PUBNUB_SEND_FILE_OPTS_INIT;
    opts.channel      = "my_channel";
    opts.file_name    = "greeting_async.txt";
    opts.data         = (const uint8_t*)content;
    opts.data_len     = strlen(content);
    opts.content_type = "text/plain";


    pubnub_future_t future = pubnub_send_file(ctx, &opts);


    pubnub_res_t rc = pubnub_async(future, on_send_complete, NULL);
    if (PUBNUB_OK != rc) {
        pubnub_future_release(future);
        pubnub_destroy(ctx);
        return EXIT_FAILURE;
    }


    /* On threaded platforms a background thread drives I/O and calls
       on_send_complete when done, so pubnub_process() here is a no-op.
       On embedded targets without threads, this same call is what
       actually drives the upload to completion. */
    while (!s_done) {
        pubnub_process(ctx);
    }


    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 72 lines

Adapted from examples/files/send_file_async.c (callback-driven, via pubnub_async). The example's own comment notes that list, download, delete, and publish-file-message support the same async pattern.

Error responses

pubnub_res_t is the universal status type for this SDK; see The pubnub_res_t result catalog for the full list. Files-specific behavior worth calling out:

Storage (S3) returns a flat XML error body on upload failure, and the SDK classifies it. EntityTooLarge becomes PUBNUB_ERR_INVALID_ARGUMENT: the file exceeds the server-configured size limit, and there is no client-side pre-check. An AccessDenied response whose message contains "expired" becomes PUBNUB_ERR_TIMEOUT: the presigned upload URL from step 1 expired before the upload ran. Any other storage failure becomes PUBNUB_ERR_TRANSPORT.
A missing publish_key in pubnub_config_t fails both pubnub_send_file() and pubnub_publish_file_message() immediately with PUBNUB_ERR_INVALID_ARGUMENT.
Files responses populate the code sub-field of pubnub_service_error_t with a Files-specific numeric sub-code that no other feature's error responses carry today. See Retrieving server error detail.

List channel files

Retrieve a page of files previously uploaded to a channel.

Method(s)

pubnub_future_t pubnub_list_files(pubnub_context_t* ctx, const pubnub_list_files_opts_t* opts);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`limit` Type: `int` Default: `0` → server default of 100	Valid range 1-100.
`next` Type: `const char*` Default: `NULL` (first page)	Borrowed. Pass the previous response's `pubnub_list_files_result_t.next` to fetch the next page.
`timeout_ms` Type: `uint32_t` Default: `0` → `pubnub_config_t.transaction_timeout_ms`	—

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_list_files_opts_t, pubnub_list_files_result_t, pubnub_file_info_t
Prerequisite — an initialized context with subscribe_key set
Feature flag — PUBNUB_ENABLE_FILES
Ownership / lifetime — every view in the result and in each pubnub_file_info_t aliases memory owned by the future and is valid only until pubnub_future_release
Blocking — never blocks; returns a pubnub_future_t immediately

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>
#include <pubnub/response.h>


#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    pubnub_list_files_opts_t opts = PUBNUB_LIST_FILES_OPTS_INIT;
    opts.channel = "my_channel";
    opts.limit   = 10;


    pubnub_future_t future = pubnub_list_files(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        pubnub_list_files_result_t r = pubnub_list_files_result(future);
        printf("files on channel (%u):\n", r.count);
        for (uint32_t i = 0; i < r.count; ++i) {
            pubnub_file_info_t f = pubnub_list_files_result_file_at(future, i);
            printf("  %.*s  id=%.*s  %u bytes\n",
                   (int)f.name.len, f.name.ptr,
                   (int)f.id.len, f.id.ptr,
                   f.size);
        }
    }
    else {
        pubnub_string_view_t err = pubnub_response_error_message(future);
        printf("list_files failed: %.*s\n", (int)err.len, err.ptr);
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 49 lines

Adapted from examples/files/list_files.c (cooperative polling).

Returns

pubnub_list_files_result_t pubnub_list_files_result(pubnub_future_t future);
pubnub_file_info_t         pubnub_list_files_result_file_at(pubnub_future_t future, size_t index);

pubnub_list_files_result_t has 2 fields:

Field	Type	Description
`count`	`uint32_t`	Number of files in this page, the loop bound for `pubnub_list_files_result_file_at`.
`next`	`pubnub_string_view_t`	Pagination token. Empty (`.len == 0`) on the last page.

pubnub_file_info_t has 4 fields:

Field	Type	Description
`id`	`pubnub_string_view_t`	File identifier.
`name`	`pubnub_string_view_t`	File name.
`size`	`uint32_t`	Size in bytes.
`created`	`pubnub_string_view_t`	ISO 8601 creation timestamp.

pubnub_list_files_result_file_at() returns a zero-initialized pubnub_file_info_t for index >= count or when the future is not yet ready. It never reads out of bounds. Every view above aliases memory owned by the future and is valid only until pubnub_future_release.

Get file URL

Build a URL that points at a previously uploaded file, without making a network call.

Method(s)

pubnub_res_t pubnub_get_file_url(pubnub_context_t*                 ctx,
                                 const pubnub_get_file_url_opts_t* opts,
                                 char*                             buf,
                                 size_t                            buf_size,
                                 size_t*                           out_len);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_id` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_name` * Type: `const char*` Default: —	Borrowed, NUL-terminated.

There is no timeout_ms field on pubnub_get_file_url_opts_t. The call makes no network request.

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_get_file_url_opts_t
Prerequisite — an initialized context; the URL is built from the context's configured origin and subscribe_key
Feature flag — PUBNUB_ENABLE_FILES
Ownership / lifetime — buf is a caller-owned buffer; out_len receives the number of bytes the URL needs (excluding the NUL terminator) regardless of whether buf was large enough, so you can probe the required size even when the call returns PUBNUB_ERR_BUFFER_TOO_SMALL
Blocking — synchronous, local computation only; returns a pubnub_res_t directly, not a pubnub_future_t

This URL has no signature, no expiry, and no crypto awareness

pubnub_get_file_url() makes no network request. It only formats https://{origin}/v1/files/{subscribe_key}/channels/{channel}/files/{id}/{name} into your buffer from the context's configured origin and subscribe_key, plus the three identifiers you pass in. Nothing about the result is signed or time-limited, and the function has no awareness of whether the target file was encrypted at upload time. If the file was uploaded with a crypto_module configured, this URL still points at the encrypted bytes in storage. Only pubnub_download_file() performs decryption. Anyone who fetches this URL directly, including a browser, receives exactly what is stored: ciphertext if the sender encrypted the file, plaintext otherwise. Do not hand this URL to an untrusted party for an encrypted file expecting it to serve plaintext.

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>


#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    pubnub_get_file_url_opts_t opts = PUBNUB_GET_FILE_URL_OPTS_INIT;
    opts.channel   = "my_channel";
    opts.file_id   = "abc-123";
    opts.file_name = "report.pdf";


    char   url_buf[512];
    size_t url_len = 0;


    pubnub_res_t rc = pubnub_get_file_url(ctx, &opts, url_buf, sizeof(url_buf), &url_len);
    if (PUBNUB_OK == rc) {
        printf("URL: %.*s\n", (int)url_len, url_buf);
    }
    else if (PUBNUB_ERR_BUFFER_TOO_SMALL == rc) {
        printf("buffer too small; need %zu bytes\n", url_len);
    }


    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 36 lines

Adapted from the header's own @code example (files.h:789-800).

Returns

pubnub_get_file_url() returns a pubnub_res_t directly:

Value	Meaning
`PUBNUB_OK`	`buf` now holds the URL; `out_len` (if non-`NULL`) holds its length.
`PUBNUB_ERR_BUFFER_TOO_SMALL`	`buf` was too small. `out_len` still holds the length actually needed. Resize and retry.
`PUBNUB_ERR_INVALID_ARGUMENT`	`ctx`, `opts->channel`, or `buf` was `NULL`.

See The pubnub_res_t result catalog for the full set of values this SDK can return.

Download file

Method(s)

pubnub_future_t pubnub_download_file(pubnub_context_t* ctx, const pubnub_download_file_opts_t* opts);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_id` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_name` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`timeout_ms` Type: `uint32_t` Default: `0` → `pubnub_config_t.transaction_timeout_ms`	—

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_download_file_opts_t, pubnub_download_file_result_t
Prerequisite — an initialized context with subscribe_key set
Feature flag — PUBNUB_ENABLE_FILES
Ownership / lifetime — data in the result is borrowed and valid only until pubnub_future_release; there is no streaming API, so the entire file is buffered in memory until then
Buffers — PUBNUB_CFG_FILES_MAX_DOWNLOAD_SIZE (default 0, unlimited) caps the accepted response body; exceeding it fails the future with PUBNUB_ERR_BUFFER_TOO_SMALL before any bytes reach you
Blocking — never blocks; returns a pubnub_future_t immediately

A silent decryption failure returns ciphertext, not an error

pubnub_download_file_result_t.decrypted is 1 only when a crypto_module is configured on the context and decryption succeeds. In that case, data/data_len are the plaintext bytes. Otherwise, whether no crypto module is configured or decryption fails for any reason, the function does not fail the future and raises no error. It silently falls back to returning data/data_len as the raw, un-decrypted response body, with decrypted set to 0. A caller that writes data to disk without checking decrypted first can save ciphertext to disk while believing it has the original file. Nothing signals that anything went wrong.

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>
#include <pubnub/response.h>


#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    pubnub_download_file_opts_t opts = PUBNUB_DOWNLOAD_FILE_OPTS_INIT;
    opts.channel   = "my_channel";
    opts.file_id   = "abc-123";
    opts.file_name = "greeting.txt";


    pubnub_future_t future = pubnub_download_file(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        pubnub_download_file_result_t r = pubnub_download_file_result(future);
        if (r.decrypted) {
            printf("downloaded %zu decrypted bytes\n", r.data_len);
        }
        else {
            printf("downloaded %zu bytes, NOT decrypted -- "
                   "verify crypto_module configuration before trusting this content\n",
                   r.data_len);
        }
    }
    else {
        pubnub_string_view_t err = pubnub_response_error_message(future);
        printf("download failed: %.*s\n", (int)err.len, err.ptr);
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 49 lines

Adapted from examples/files/download_file.c (cooperative polling), extended to check the decrypted flag described in the warning above. The shipped example prints the bytes without checking it.

Returns

pubnub_download_file_result_t pubnub_download_file_result(pubnub_future_t future);

pubnub_download_file_result_t has 3 fields:

Field	Type	Description
`data`	`const uint8_t*`	Borrowed. Valid until `pubnub_future_release`.
`data_len`	`size_t`	Byte count of `data`.
`decrypted`	`uint8_t`	`1` when a `crypto_module` is configured and decryption succeeded — `data`/`data_len` are plaintext. `0` in every other case: no crypto module configured, decryption not attempted, or decryption failed silently. When `0`, `data`/`data_len` are the raw (possibly still-encrypted) bytes from storage. See the warning above.

Delete file

Method(s)

pubnub_future_t pubnub_delete_file(pubnub_context_t* ctx, const pubnub_delete_file_opts_t* opts);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_id` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_name` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`timeout_ms` Type: `uint32_t` Default: `0` → `pubnub_config_t.transaction_timeout_ms`	—

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_delete_file_opts_t. There is no feature-specific result struct.
Prerequisite — an initialized context with subscribe_key set
Feature flag — PUBNUB_ENABLE_FILES
Blocking — never blocks; returns a pubnub_future_t immediately

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>


#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    pubnub_delete_file_opts_t opts = PUBNUB_DELETE_FILE_OPTS_INIT;
    opts.channel   = "my_channel";
    opts.file_id   = "abc-123";
    opts.file_name = "report.pdf";


    pubnub_future_t future = pubnub_delete_file(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        printf("file deleted\n");
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 36 lines

Adapted from the header's own @code example (files.h:647-663).

Returns

pubnub_delete_file() has no feature-specific result struct and no dedicated result-accessor function. Check pubnub_future_status(future) directly: PUBNUB_OK means the file was removed from storage. See The pubnub_res_t result catalog for every other value it can return.

Publish file message

Publish a message announcing a file that is already in storage, without uploading anything.

Call this directly when you already have a stored file's id and name. Most often that's from a failed pubnub_send_file()'s partial-success result (see Send file), but it can also come from pubnub_list_files_result_file_at() for a file uploaded earlier. pubnub_publish_file_message() issues only the publish step. It never touches storage and never re-uploads content. Internally, pubnub_send_file() calls this same function for its own third step, so calling it directly for the recovery path exercises exactly the code that step already runs.

Method(s)

pubnub_future_t
pubnub_publish_file_message(pubnub_context_t*                         ctx,
                            const pubnub_publish_file_message_opts_t* opts);

* required

Parameter	Description
`channel` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_id` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`file_name` * Type: `const char*` Default: —	Borrowed, NUL-terminated.
`message` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated. Must be valid JSON. Encrypted before publish when a `crypto_module` is configured.
`meta` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated.
`custom_message_type` Type: `const char*` Default: `NULL`	Borrowed, NUL-terminated, 3-50 characters.
`store` Type: `int` Default: `1` (store)	Whether to store the file message in history.
`ttl` Type: `unsigned int` Default: `0` (account default)	Minutes to retain the file message.
`timeout_ms` Type: `uint32_t` Default: `0` → `pubnub_config_t.transaction_timeout_ms`	—

C-family contract

Header — #include <pubnub/features/files.h>
Types — pubnub_publish_file_message_opts_t, pubnub_publish_file_message_result_t
Prerequisite — an initialized context with publish_key and subscribe_key set
Feature flag — PUBNUB_ENABLE_FILES
Ownership / lifetime — message/meta are borrowed strings; the result's timetoken view is valid only until pubnub_future_release
Blocking — never blocks; returns a pubnub_future_t immediately

Sample code

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>


#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.publish_key   = "demo";
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    pubnub_publish_file_message_opts_t opts = PUBNUB_PUBLISH_FILE_MESSAGE_OPTS_INIT;
    opts.channel   = "my_channel";
    opts.file_id   = "abc-123";
    opts.file_name = "report.pdf";
    opts.message   = "{\"caption\":\"Q4 report\"}";


    pubnub_future_t future = pubnub_publish_file_message(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        pubnub_publish_file_message_result_t r = pubnub_publish_file_message_result(future);
        printf("published at %.*s\n", (int)r.timetoken.len, r.timetoken.ptr);
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 39 lines

Adapted from the header's own @code example (files.h:737-758).

Returns

pubnub_publish_file_message_result_t pubnub_publish_file_message_result(pubnub_future_t future);

pubnub_publish_file_message_result_t has a single field, timetoken (pubnub_timetoken_t): the publish timetoken, valid only after the future completes with PUBNUB_OK.

Other examples

Trigger mobile push notifications for a file message

PubNub forwards a published message to APNs and/or FCM when its payload contains the reserved pn_apns and/or pn_fcm keys, the same mechanism used for any ordinary published message. Because pubnub_publish_file_message() ultimately publishes a JSON message like any other, include those keys in the message JSON alongside your own content to trigger a push notification for the file:

#include <pubnub/client.h>
#include <pubnub/features/files.h>
#include <pubnub/future.h>


#include <stdio.h>
#include <stdlib.h>


int main(void)
{
    pubnub_config_t cfg = pubnub_config_defaults();
    cfg.publish_key   = "demo";
    cfg.subscribe_key = "demo";
    cfg.user_id       = "my_unique_user_id";


    pubnub_context_t* ctx = pubnub_create(&cfg);
    if (NULL == ctx) {
        return EXIT_FAILURE;
    }


    static const char message[] =
        "{\"file\":{\"description\":\"Q4 report\"},"
        "\"pn_apns\":{\"aps\":{\"alert\":\"New file: report.pdf\"}},"
        "\"pn_fcm\":{\"notification\":{\"title\":\"New file\",\"body\":\"report.pdf\"}}}";


    pubnub_publish_file_message_opts_t opts = PUBNUB_PUBLISH_FILE_MESSAGE_OPTS_INIT;
    opts.channel   = "my_channel";
    opts.file_id   = "abc-123";
    opts.file_name = "report.pdf";
    opts.message   = message;


    pubnub_future_t future = pubnub_publish_file_message(ctx, &opts);
    while (!pubnub_future_is_ready(future)) {
        pubnub_process(ctx);
    }


    if (PUBNUB_OK == pubnub_future_status(future)) {
        printf("published with push payload\n");
    }


    pubnub_future_release(future);
    pubnub_destroy(ctx);
    return EXIT_SUCCESS;
}
show all 43 lines

This sample follows the pn_apns/pn_fcm payload convention described in Mobile Push.

Subscribers to a channel receive a file-share event through the same subscribe stream as any other message, decoded through a dedicated typed extractor. The listener callback that receives it takes a const pubnub_subscribe_event_t*. See The subscribe event struct for its fields and the full discriminant list.

Method(s)

pubnub_res_t pubnub_subscribe_event_file(pubnub_context_t*               ctx,
                                         const pubnub_subscribe_event_t* event,
                                         pubnub_subscribe_file_event_t*  out);

pubnub_subscribe_file_event_t has 7 fields:

Field	Type	Description
`channel`	`pubnub_string_view_t`	Channel the file was published on.
`subscription`	`pubnub_string_view_t`	Subscription match pattern.
`publisher`	`pubnub_string_view_t`	Publisher's `user_id`.
`file_id`	`pubnub_string_view_t`	Server-generated file identifier.
`file_name`	`pubnub_string_view_t`	File name.
`message`	`const pubnub_json_value_t*`	JSON-node pointer to the optional message attached at publish time. `NULL` when absent. Valid only inside the listener callback.
`timetoken`	`pubnub_string_view_t`	Publish timetoken.

C-family contract

Header — #include <pubnub/features/subscribe_types.h> (struct), #include <pubnub/features/subscribe.h> (extractor)
Types — pubnub_subscribe_file_event_t, pubnub_subscribe_event_t
Prerequisite — an active subscription delivering events to a listener; see Listeners
Feature flag — PUBNUB_ENABLE_SUBSCRIBE, not PUBNUB_ENABLE_FILES. This extractor compiles and works even in a build with Files disabled
Ownership / lifetime — every view field aliases the subscribe event; message is a JSON-node pointer valid only for the duration of the listener callback
Blocking — synchronous, local-only; not a pubnub_future_t operation

Two similarly-named enums: use the subscribe one here

pubnub_subscribe_event_file() validates that event->type equals PUBNUB_SUBSCRIBE_FILE, a member of pubnub_subscribe_message_type_t. Do not confuse this with PUBNUB_EVENT_TYPE_FILE, a similarly-named member of History's own pubnub_event_type_t used on pubnub_history_message_result_t (see The pubnub_event_type_t enum). The two enums are unrelated types on unrelated structs. Use PUBNUB_SUBSCRIBE_FILE here.

Sample code

#include <pubnub/client.h>
#include <pubnub/features/subscribe.h>
#include <pubnub/features/subscribe_types.h>


#include <stdio.h>


static void on_message(const pubnub_subscribe_event_t* event, void* user_data)
{
    pubnub_context_t* ctx = (pubnub_context_t*)user_data;


    if (PUBNUB_SUBSCRIBE_FILE != event->type) {
        return;
    }


    pubnub_subscribe_file_event_t file;
    if (PUBNUB_OK == pubnub_subscribe_event_file(ctx, event, &file)) {
        printf("file_id: %.*s, file_name: %.*s\n",
               (int)file.file_id.len, file.file_id.ptr,
               (int)file.file_name.len, file.file_name.ptr);
    }
}
show all 21 lines

This callback registers like any other message listener. See Listeners for how to attach it to a subscription and drive the event loop.

Returns

pubnub_subscribe_event_file() returns PUBNUB_OK on success, PUBNUB_ERR_INVALID_ARGUMENT if any argument is NULL or event->type is not PUBNUB_SUBSCRIBE_FILE, and PUBNUB_ERR_SERIALIZATION if the event body fails to parse. On success, out is populated with the fields listed above.

Two feature flags, two different scopes

Send file​

Method(s)​

One future, three HTTP requests, one request-pool slot

A failed publish step still means the file exists. Do not call pubnub_send_file() again.

Sample code​

Returns​

Other examples​

Recover from a publish failure without re-uploading​

Send file asynchronously​

Error responses​

List channel files​

Method(s)​

Sample code​

Returns​

Get file URL​

Method(s)​

This URL has no signature, no expiry, and no crypto awareness

Sample code​

Returns​

Download file​

Method(s)​

A silent decryption failure returns ciphertext, not an error

Sample code​

Returns​

Delete file​

Method(s)​

Sample code​

Returns​

Publish file message​

Method(s)​

Sample code​

Returns​

Other examples​

Trigger mobile push notifications for a file message​

Receive file share events​

Method(s)​

Two similarly-named enums: use the subscribe one here

Sample code​

Returns​

Send file

Method(s)

Sample code

Returns

Other examples

Recover from a publish failure without re-uploading

Send file asynchronously

Error responses

List channel files

Method(s)

Sample code

Returns

Get file URL

Method(s)

Sample code

Returns

Download file

Method(s)

Sample code

Returns

Delete file

Method(s)

Sample code

Returns

Publish file message

Method(s)

Sample code

Returns

Other examples

Trigger mobile push notifications for a file message

Receive file share events

Method(s)

Sample code

Returns