diff --git a/.pubnub.yml b/.pubnub.yml index 82cc51f1..5d10eea9 100644 --- a/.pubnub.yml +++ b/.pubnub.yml @@ -1,8 +1,17 @@ name: c-core schema: 1 -version: "7.3.6" +version: "7.3.7" scm: github.com/pubnub/c-core changelog: + - date: 2026-10-26 + version: v7.3.7 + changes: + - type: bug + text: "`pubnub_generate_uuid_v1_time` copied from the address of the `i_node` parameter instead of the six node bytes the caller passed. The node field of a version 1 UUID now matches that input." + - type: bug + text: "`pbmd5_digest` and `pbmd5_digest_str` passed `M_ctx` to `MD5_Final` while the bytes were hashed in `M_ctx_`. Those macros now finalize the context they initialized and updated, in both `lib/md5/pbmd5.h` and `openssl/pbmd5.h`." + - type: bug + text: "When `PUBNUB_USE_EXTERN_C` is set, `pubnub_version.h` and the POSIX and Windows C++ version sources declare and define `pubnub_uname`, `pubnub_uagent`, and the other version functions with C linkage. C++ callers, including core sources built as C++, resolve the same symbols as C." - date: 2026-10-08 version: v7.3.6 changes: @@ -1271,7 +1280,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1330,7 +1339,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1389,7 +1398,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1444,7 +1453,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1498,7 +1507,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1547,7 +1556,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" @@ -1593,7 +1602,7 @@ sdks: - distribution-type: source code distribution-repository: GitHub release package-name: C-Core - location: https://github.com/pubnub/c-core/releases/tag/v7.3.6 + location: https://github.com/pubnub/c-core/releases/tag/v7.3.7 requires: - name: "miniz" min-version: "2.0.8" diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c991097..974bcc15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,11 @@ +## v7.3.7 +October 26 2026 + +#### Fixed +- `pubnub_generate_uuid_v1_time` copied from the address of the `i_node` parameter instead of the six node bytes the caller passed. The node field of a version 1 UUID now matches that input. +- `pbmd5_digest` and `pbmd5_digest_str` passed `M_ctx` to `MD5_Final` while the bytes were hashed in `M_ctx_`. Those macros now finalize the context they initialized and updated, in both `lib/md5/pbmd5.h` and `openssl/pbmd5.h`. +- When `PUBNUB_USE_EXTERN_C` is set, `pubnub_version.h` and the POSIX and Windows C++ version sources declare and define `pubnub_uname`, `pubnub_uagent`, and the other version functions with C linkage. C++ callers, including core sources built as C++, resolve the same symbols as C. Fixed the following issues reported by [@MarcGeh](https://github.com/MarcGeh), [@spectrbro](https://github.com/spectrbro) and [@polar91760](https://github.com/polar91760): [#106](https://github.com/pubnub/c-core/issues/106), [#242](https://github.com/pubnub/c-core/issues/242) and [#225](https://github.com/pubnub/c-core/issues/225). + ## v7.3.6 October 08 2026 diff --git a/README.md b/README.md index e94bc17a..9a6bd1ef 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,192 @@ -![PubNub C-Core SDK](images/c-core-header.png) +> **Legacy SDK:** C-Core remains supported for existing applications. If you are starting a new C project, use the [new PubNub C SDK](https://www.pubnub.com/docs/sdks/c). -## Pubnub C/C++ client libraries +# PubNub C-Core (legacy) SDK -[![Build Status](https://travis-ci.com/pubnub/c-core.svg?branch=master)](https://travis-ci.com/pubnub/c-core) +[![GitHub release](https://img.shields.io/github/v/release/pubnub/c-core)](https://github.com/pubnub/c-core/releases) -This repository has the source for the C/C++ client libraries, -designed mostly for embedded systems, but perfectly suitable for -"regular" (POSIX, Windows) systems, too. +PubNub provides global infrastructure for real-time, interactive applications. -### Official Docs -Docs for C/C++ for Posix, Windows, as well as FreeRTOS and other embedded platforms are available at -https://www.pubnub.com/docs/posix-c/pubnub-c-sdk +Publish and receive messages in C-Core (legacy). Use this SDK for existing portable C applications on the platforms maintained by C-Core. -## Please direct all Support Questions and Concerns to Support@PubNub.com +[Documentation](https://www.pubnub.com/docs/sdks/c-core) · [API reference](https://www.pubnub.com/docs/sdks/c-core/api-reference/publish-and-subscribe) · [Changelog](https://www.pubnub.com/docs/sdks/c-core/changelog) · [Support](https://support.pubnub.com/) -## Build +## Requirements -Our repository can be build via two different approaches: +| Requirement | Supported version or setup | +| --- | --- | +| C or C++ compiler | [Use the compiler and platform requirements listed in C-Core Platform Support](https://www.pubnub.com/docs/sdks/c-core/platform-support) | +| Platform | [POSIX, Windows, FreeRTOS, Mbed, and other maintained C-Core targets](https://www.pubnub.com/docs/sdks/c-core/platform-support) | +| Platform-specific networking and TLS implementation | Build and link the C-Core platform implementation matching the target operating system and networking stack. | -### CMake (new but recommended) +## Installation -You can build repository using CMake using our [CMakeLists.txt file](CMakeLists.txt). +Clone the repository and build the POSIX target. Run `make` from the `posix` directory. The makefile paths are relative to that directory. -- Unix: ```sh -mkdir build && cd build -cmake .. -make +git clone https://github.com/pubnub/c-core.git +cd c-core/posix +make -f posix.mk ``` -- Windows (MSVS tools required): -```sh -mkdir build && cd build -cmake .. -G "NMake Makefiles" -nmake +For Windows, FreeRTOS, OpenSSL, Qt, and CMake, see [environment setup](https://www.pubnub.com/docs/sdks/c-core). Platform notes are in [`posix/README.md`](posix/README.md), [`windows/README.md`](windows/README.md), [`openssl/README.md`](openssl/README.md), [`freertos/README.md`](freertos/README.md), and [`CMakeLists.txt`](CMakeLists.txt). + +## Quickstart + +This example runs in POSIX C. It subscribes to `hello_world`, publishes one message, and prints the received text. + +A sync context runs one transaction at a time. The first subscribe connects and stores a timetoken. The sample publishes after that, then subscribes again to receive the message. + +### Get your keys + +1. Open the [PubNub Admin Portal](https://admin.pubnub.com/). +2. Create an app and a keyset for development, or select an existing development keyset. +3. Copy its publish key and subscribe key. + +If Access Manager is enabled, obtain a token from your trusted backend and call `pubnub_set_auth_token(pb, token)` before accessing protected resources. Keep the secret key on the backend. + +### Send and receive a message + +Create `hello_world.c` and build it with the POSIX sync library from the installation step. + +Replace the key placeholders. Use a User ID that identifies the user or device in your app. + +```c +#include "pubnub_sync.h" + +#include +#include + +int main(void) +{ + enum pubnub_res result; + char const* message; + pubnub_t* pb = pubnub_alloc(); + + if (NULL == pb) { + return EXIT_FAILURE; + } + + /* Replace with your keys from the Admin Portal. + Use a User ID that identifies the user or device. */ + pubnub_init(pb, "YOUR_PUBLISH_KEY", "YOUR_SUBSCRIBE_KEY"); + pubnub_set_user_id(pb, "hello-world-user"); + + /* Connect to hello_world. This first subscribe only gets a timetoken. + Messages published before it finishes are missed. */ + result = pubnub_subscribe(pb, "hello_world", NULL); + if (PNR_STARTED == result) { + result = pubnub_await(pb); + } + if (PNR_OK != result) { + printf("Failed to connect\n"); + pubnub_free(pb); + return EXIT_FAILURE; + } + + /* Drop anything returned by the connect so the next subscribe can start. */ + while (NULL != pubnub_get(pb)) { + continue; + } + + /* Publish Hello world. The payload is a JSON string. */ + result = pubnub_publish(pb, "hello_world", "\"Hello world\""); + if (PNR_STARTED == result) { + result = pubnub_await(pb); + } + if (PNR_OK != result) { + printf("Failed to publish\n"); + pubnub_free(pb); + return EXIT_FAILURE; + } + + /* Subscribe again to receive the message published above. */ + result = pubnub_subscribe(pb, "hello_world", NULL); + if (PNR_STARTED == result) { + result = pubnub_await(pb); + } + if (PNR_OK != result) { + printf("Failed to receive\n"); + pubnub_free(pb); + return EXIT_FAILURE; + } + + message = pubnub_get(pb); + if (NULL == message) { + printf("No message received\n"); + pubnub_free(pb); + return EXIT_FAILURE; + } + printf("%s\n", message); + + pubnub_free(pb); + return EXIT_SUCCESS; +} ``` -- for other platforms you can search for information in [FreeRTOS](freertos/README.md) or [QT](qt/README.md) READMEs. +### Run the example -There are several options to be selected via switches (using GUI) or by using command line. -```sh -cmake .. -DOPENSSL=ON -DEXAMPLES=ON +Build `hello_world.c` with the POSIX sync library, then run the `hello_world` binary. + +The terminal should show: + +```text +"Hello world" ``` -Check the [CMakeLists file](CMakeLists.txt) for more info. +The printed text includes quotes because the published payload is a JSON string. + +Cancel unfinished transactions with `pubnub_cancel()` where necessary and release every context created with `pubnub_alloc()` by calling `pubnub_free()`. -### Makefiles (legacy) +For a complete application, see the [getting started guide](https://www.pubnub.com/docs/sdks/c-core). -You can build our SDK using standard tooling depending on OS you're using. -For more info check those links: +## Next steps -- [posix](posix/README.md), -- [windows](windows/README.md), -- [openssl](openssl/README.md), -- [freertos](freertos/README.md), +| Task | Documentation | +| --- | --- | +| Configure the client | [Configuration](https://www.pubnub.com/docs/sdks/c-core/api-reference/configuration) | +| Work with subscriptions and messages | [Publish & Subscribe](https://www.pubnub.com/docs/sdks/c-core/api-reference/publish-and-subscribe) | +| Check channel occupancy | [Presence](https://www.pubnub.com/docs/sdks/c-core/api-reference/presence) | +| Read message history | [Message Persistence](https://www.pubnub.com/docs/sdks/c-core/api-reference/storage-and-playback) | -depending on what fits you best. +## Build with an AI coding assistant -## Directory Organization +The [PubNub MCP server](https://www.pubnub.com/docs/ai/pubnub-mcp-server) gives an AI coding assistant access to PubNub SDK documentation and PubNub APIs. Connect the assistant to the hosted server at `https://mcp.pubnub.com`, or run `npx @pubnub/mcp@latest` locally. -The directories of the library repository are: +The [server repository](https://github.com/pubnub/pubnub-mcp-server) has setup steps for VS Code, Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, and OpenCode. -- `core` : The core part, with modules portable to all, or most, libraries for - specific platforms +## Before production -- `lib` : Modules for libraries that are available on more than one platform +Use [Access Manager](https://www.pubnub.com/docs/sdks/c-core/api-reference/access-manager) to grant each client the permissions it needs. Keep the secret key on your backend. Never include it in a distributed client. -- `windows` : Modules and Makefile for the Windows platform +Reuse allocated C-Core contexts instead of allocating one for every operation. Cancel unfinished work with `pubnub_cancel()` and release contexts created by `pubnub_alloc()` with `pubnub_free()`. -- `posix` : Modules and Makefile for POSIX OSes (tested mostly on Linux) +Live delivery through PubNub SDKs is at-most-once. A subscriber can miss messages while disconnected or if its buffer overflows. For longer-gap recovery, see [Message Persistence](https://www.pubnub.com/docs/sdks/c-core/api-reference/storage-and-playback). -- `openssl`: Modules and Makefile(s) for OpenSSL (on POSIX and Windows) +## Troubleshooting -- `mbedtls`: Modules for MBedTLS +| Symptom | Check | +| --- | --- | +| The application links the wrong C-Core platform implementation | Build and link the implementation matching the target operating system and networking stack. See [C-Core Platform Support](https://www.pubnub.com/docs/sdks/c-core/platform-support). | +| A publish succeeds but no message appears | Check the keyset and channel name. The first `pubnub_subscribe()` only connects. Publish after that call finishes, then subscribe again to receive the message. | +| A new C application is being started with C-Core | C-Core is the legacy SDK. New C applications should use the [new C SDK](https://www.pubnub.com/docs/sdks/c). | +| Extra clients or duplicate messages during development | Reuse C-Core contexts rather than allocating contexts repeatedly. Cancel unfinished work and release allocated contexts when their owner terminates. | -- `cpp`: Modules, Makefile(s) and examples for the C++ wrapper +For setup help, see [troubleshooting](https://www.pubnub.com/docs/sdks/c-core/troubleshoot). Check [network status](https://status.pubnub.com/) for service incidents. -- `qt`: Modules, Qt projects and examples for Qt +## Releases -- `freertos` : Modules and Makefile for the FreeRTOS and ESP32 platforms +Read the [changelog](https://www.pubnub.com/docs/sdks/c-core/changelog) before upgrading. -- `microchip_harmony` : Modules and project for Microchip MPLAB Harmony +To move an existing C-Core v7 application to the new C SDK, follow [Migrating from C-Core v7](https://www.pubnub.com/docs/sdks/c/migration-guides/migrating-from-c-core-v7). -- `unreal` : Unreal Engine integration module +## Support and contributions - -## Files +For setup or account help, contact [PubNub Support](https://support.pubnub.com/). -In this root directory we have some files, too: +For a reproducible SDK bug, use [GitHub Issues](https://github.com/pubnub/c-core/issues). Include the SDK version, runtime, and a small reproduction with credentials removed. -- `posix.mk`: a "master" Makefile for POSIX - will build all the POSIX - Makefiles there are (doesn't build Qt - you might not have Qt) -- `windows.mk`: a "master" Makefile for Windows - will build all the - Windows Makefiles there are (doesn't build Qt, you might not have Qt). For UWP support, use uwp.mk Makefile. -- `.pubnub.yml`: Standard Pubnub library description in YAML -- `.travis.yml`: Configuration for Travis CI (POSIX: Linux and MacOS) -- `.appveyor.yml`: Configuration for Appveyor CI (Windows) -- `.clang-format`: Configuration for Clang-format tool that we use to format - C/C++ source code +See [CONTRIBUTING.md](https://github.com/pubnub/c-core/blob/master/CONTRIBUTING.md) and run the test suite for the affected platform before opening a pull request. - -## Contributing +## License -Please read the [Contribution Guidelines](CONTRIBUTING.md). +See the [PubNub Software Development Kit License](https://github.com/pubnub/c-core/blob/master/LICENSE). diff --git a/core/pubnub_generate_uuid.c b/core/pubnub_generate_uuid.c index 0290422b..650cf122 100644 --- a/core/pubnub_generate_uuid.c +++ b/core/pubnub_generate_uuid.c @@ -47,7 +47,7 @@ int pubnub_generate_uuid_v1_time( ud->clock_seq_hi_and_reserved = (*io_clock_seq & 0x3F00) >> 8; ud->clock_seq_hi_and_reserved |= 0x80; - memcpy(&ud->node, &i_node, sizeof ud->node); + memcpy(ud->node, i_node, sizeof ud->node); memcpy(s_timestamp, i_timestamp, sizeof s_timestamp); return 0; diff --git a/core/pubnub_version.h b/core/pubnub_version.h index e28fbc38..68c90efb 100644 --- a/core/pubnub_version.h +++ b/core/pubnub_version.h @@ -10,6 +10,11 @@ platforms and have the same interface in all of them. */ +/* Match cpp/pubnub_version_*.cpp: when PUBNUB_USE_EXTERN_C is set, C++ + callers (including core .c files built with -x c++ /TP) use C linkage. */ +#if defined(__cplusplus) && PUBNUB_USE_EXTERN_C +extern "C" { +#endif /** Returns a string with the name of the Pubnub SDK client you are using. @@ -31,6 +36,8 @@ PUBNUB_EXTERN char const *pubnub_uname(void); */ PUBNUB_EXTERN char const *pubnub_uagent(void); - +#if defined(__cplusplus) && PUBNUB_USE_EXTERN_C +} +#endif #endif /* !defined INC_PUBNUB_VERSION */ diff --git a/core/pubnub_version_internal.h b/core/pubnub_version_internal.h index 398a1237..34977da3 100644 --- a/core/pubnub_version_internal.h +++ b/core/pubnub_version_internal.h @@ -3,7 +3,7 @@ #define INC_PUBNUB_VERSION_INTERNAL -#define PUBNUB_SDK_VERSION "7.3.6" +#define PUBNUB_SDK_VERSION "7.3.7" #endif /* !defined INC_PUBNUB_VERSION_INTERNAL */ diff --git a/cpp/pubnub_version_posix.cpp b/cpp/pubnub_version_posix.cpp index 3c801b9e..f49c4a7f 100644 --- a/cpp/pubnub_version_posix.cpp +++ b/cpp/pubnub_version_posix.cpp @@ -1,4 +1,7 @@ /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */ +#if PUBNUB_USE_EXTERN_C +extern "C" { +#endif #include "core/pubnub_version.h" #include "core/pubnub_version_internal.h" @@ -29,3 +32,6 @@ char const *pubnub_uagent(void) { return PUBNUB_SDK_NAME "-PubNub-C++-core/" PUBNUB_SDK_VERSION; } +#if PUBNUB_USE_EXTERN_C +} +#endif diff --git a/cpp/pubnub_version_windows.cpp b/cpp/pubnub_version_windows.cpp index 1aa4a660..dc5b7349 100644 --- a/cpp/pubnub_version_windows.cpp +++ b/cpp/pubnub_version_windows.cpp @@ -1,4 +1,7 @@ /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */ +#if PUBNUB_USE_EXTERN_C +extern "C" { +#endif #include "core/pubnub_version.h" #include "core/pubnub_version_internal.h" @@ -29,3 +32,6 @@ char const *pubnub_uagent(void) { return PUBNUB_SDK_NAME "-PubNub-C++-core/" PUBNUB_SDK_VERSION; } +#if PUBNUB_USE_EXTERN_C +} +#endif diff --git a/lib/md5/pbmd5.h b/lib/md5/pbmd5.h index e600068f..ca810f3f 100644 --- a/lib/md5/pbmd5.h +++ b/lib/md5/pbmd5.h @@ -61,7 +61,7 @@ #define pbmd5_digest(m, l, d) do { MD5_CTX M_ctx_; \ MD5_Init(&M_ctx_); \ MD5_Update(&M_ctx_, (m), (l)); \ - MD5_Final((d), &M_ctx); \ + MD5_Final((d), &M_ctx_); \ } while (0) /** This helper macro will calculate the MD5 on the message in @p str, @@ -71,7 +71,7 @@ #define pbmd5_digest_str(str, d) do { MD5_CTX M_ctx_; \ MD5_Init(&M_ctx_); \ MD5_Update(&M_ctx_, (str), strlen(str)); \ - MD5_Final((d), &M_ctx); \ + MD5_Final((d), &M_ctx_); \ } while (0) #endif /* !defined INC_PBMD5 */ \ No newline at end of file diff --git a/openssl/pbmd5.h b/openssl/pbmd5.h index 06dc3fd5..4e7b9860 100644 --- a/openssl/pbmd5.h +++ b/openssl/pbmd5.h @@ -58,7 +58,7 @@ #define pbmd5_digest(m, l, d) do { MD5_CTX M_ctx_; \ MD5_Init(&M_ctx_); \ MD5_Update(&M_ctx_, (m), (l)); \ - MD5_Final((d), &M_ctx); \ + MD5_Final((d), &M_ctx_); \ } while (0) /** This helper macro will calculate the MD5 on the message in @p str, @@ -68,7 +68,7 @@ #define pbmd5_digest_str(str, d) do { MD5_CTX M_ctx_; \ MD5_Init(&M_ctx_); \ MD5_Update(&M_ctx_, (str), strlen(str)); \ - MD5_Final((d), &M_ctx); \ + MD5_Final((d), &M_ctx_); \ } while (0) #endif /* !defined INC_PBMD5 */