# Events (/sdks/cpp/reference/events)



Fire-and-forget event messaging. Events are delivered to all active subscribers in real time and are not persisted.

## Types [#types]

### Event [#event]

Built via `Event::Builder`. Required field: `channel`.

```cpp
auto event_or = kubemq::Event::Builder()
    .SetChannel("notifications")
    .SetBody("hello")
    .SetMetadata("greeting")
    .AddTag("env", "prod")
    .Build();
```

| Method           | Type                 | Required | Description               |
| ---------------- | -------------------- | -------- | ------------------------- |
| `SetChannel(s)`  | `string`             | Yes      | Target channel name       |
| `SetBody(s)`     | `string`             | No       | Message body              |
| `SetMetadata(s)` | `string`             | No       | String metadata           |
| `SetId(s)`       | `string`             | No       | Event ID (auto-generated) |
| `SetClientId(s)` | `string`             | No       | Override client ID        |
| `SetTags(m)`     | `map<string,string>` | No       | Key-value tags            |
| `AddTag(k, v)`   | `string, string`     | No       | Add a single tag          |

### EventReceive [#eventreceive]

Received in subscription callbacks.

| Field       | Type                 | Description                   |
| ----------- | -------------------- | ----------------------------- |
| `id`        | `string`             | Event identifier              |
| `channel`   | `string`             | Channel name                  |
| `metadata`  | `string`             | String metadata               |
| `body`      | `string`             | Message body                  |
| `timestamp` | `int64_t`            | Unix nanoseconds              |
| `sequence`  | `uint64_t`           | Always 0 for non-store events |
| `tags`      | `map<string,string>` | Key-value tags                |

## Methods [#methods]

### SendEvent [#sendevent]

```cpp
[[nodiscard]] Status SendEvent(const Event& event);
```

Send a single fire-and-forget event. Returns `Status` indicating success or failure.

### PublishEvent [#publishevent]

```cpp
[[nodiscard]] Status PublishEvent(
    const std::string& channel, const std::string& body,
    const std::string& metadata = "",
    const std::unordered_map<std::string, std::string>& tags = {});
```

Convenience method to build and send an event in one call.

### SendEventStream [#sendeventstream]

```cpp
[[nodiscard]] StatusOr<std::unique_ptr<EventStreamHandle>> SendEventStream(
    std::function<void(const Status&)> on_error);
```

Open a persistent bidirectional stream for high-throughput event sending. Use `handle->Send(event)` to send events and `handle->Close()` to close the stream.

### SubscribeToEvents [#subscribetoevents]

```cpp
[[nodiscard]] StatusOr<std::unique_ptr<Subscription>> SubscribeToEvents(
    const std::string& channel, const std::string& group,
    std::function<void(const EventReceive&)> on_event,
    std::function<void(const Status&)> on_error);
```

Subscribe to real-time events on a channel. Pass an empty string for `group` to receive all events (fan-out). Use `sub->Cancel()` to unsubscribe.

## Quick Usage [#quick-usage]

```cpp title="events.cc"
// Subscribe
auto sub_or = client->SubscribeToEvents("ch", "",
    [](const kubemq::EventReceive& e) {
        std::cout << "Got: " << e.body << "\n";
    },
    [](const kubemq::Status& err) {
        std::cerr << "Error: " << err.message() << "\n";
    });

// Publish
client->PublishEvent("ch", "hello", "meta", {{"key", "val"}});

// Stream
auto stream_or = client->SendEventStream(
    [](const kubemq::Status& err) { /* handle */ });
(*stream_or)->Send(event);
(*stream_or)->Close();
```

## See Also [#see-also]

* [Events Examples](/sdks/cpp/how-to/events/)
* [Events Store Reference](/sdks/cpp/reference/events-store)