> This page is for version 3.0 (Latest) (default).
> For other versions, use one of these documentation indexes:
> - 3.0 (Latest) (default): https://docs.nvidia.com/holoscan/sensor-bridge/3-0/llms.txt
> - 2.7: https://docs.nvidia.com/holoscan/sensor-bridge/2-7/llms.txt
> - Archives: https://docs.nvidia.com/holoscan/sensor-bridge/archives/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/holoscan/sensor-bridge/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/holoscan/sensor-bridge/_mcp/server.

# hololink::module::FrameMetadataInterfaceV1

> Decode the block of metadata the device sends with each frame.

Decode the block of metadata the device sends with each frame.

Along with a frame's data, the device transmits a block of metadata associated with that frame. A receiver reserves block_size() bytes for the block when it sizes the buffer it receives frames into, then passes the received block to decode() to read the values out of it.

The device writes the block in its own layout; use this service to deserialize it.

```cpp showLineNumbers={false}
#include <hololink/module/frame_metadata.hpp>
```

**Inherits from:** `hololink::module::Service< FrameMetadataInterfaceV1 >` (public)

---

## Methods

### block_size \[#blocksize]

```cpp showLineNumbers={false}
virtual size_t hololink::module::FrameMetadataInterfaceV1::block_size() const
```

The size of a frame's metadata block, in bytes.

A receiver adds this to the space it reserves for each frame, and hands decode() a block this size. The value doesn't change while the service is in use.

**Returns:** Size of the metadata block, in bytes.

### decode \[#decode]

```cpp showLineNumbers={false}
virtual hololink_module_status_t hololink::module::FrameMetadataInterfaceV1::decode(
    const void *host_memory,
    size_t host_memory_size_bytes,
    FrameMetadata &out_metadata
) const
```

Deserialize received frame metadata into `out_metadata`.

**Returns:** HOLOLINK_MODULE_OK, or HOLOLINK_MODULE_INVALID_PARAMETER when fewer than block_size() bytes are available at `host_memory`.

**Parameters**

**`host_memory`** `const void *`

The metadata block received with a frame, in host memory.

---

**`host_memory_size_bytes`** `size_t`

Bytes available at `host_memory`.

---

**`out_metadata`** `FrameMetadata &`

What the device reported about the frame.

---

### module \[#module]

```cpp showLineNumbers={false}
std::shared_ptr<Module> hololink::module::ServiceBase::module() const
```

The [Module](module) that this service was published from.

The service holds no strong reference to its [Module](module), so this does not extend the [Module](module)'s lifetime.

**Returns:** The owning [Module](module), or an empty pointer if the service has not been published or its [Module](module) no longer exists.

---

## Static methods

### get_service \[#getservice]

#### Overload 1

```cpp showLineNumbers={false}
static std::shared_ptr<FrameMetadataInterfaceV1> hololink::module::FrameMetadataInterfaceV1::get_service(
    std::shared_ptr<Module> module,
    bool allow_null = false
)
```

Fetch a module's `FrameMetadataInterfaceV1` instance.

**Returns:** The module's frame metadata service.

**Throws:** `std::runtime_error` if the module publishes no frame metadata service and allow_null is false.

**Parameters**

**`module`** `std::shared_ptr<Module>`

The module that claims the device, from [Adapter::get_module](adapter#getmodule).

---

**`allow_null`** `bool` — default: false

Return an empty pointer, rather than throwing, when the module publishes no frame metadata service.

---

#### Overload 2

```cpp showLineNumbers={false}
static std::shared_ptr<FrameMetadataInterfaceV1> hololink::module::Service<FrameMetadataInterfaceV1>::get_service(
    std::shared_ptr<Module> module,
    const char *instance_id,
    bool allow_null = false
)
```

Type-safe way to fetch a std::shared_ptr to an instance of \<Derived> from a [Module](module).

Note that [Module](module) usually caches instances, it's likely that calls to get_service with the same locator_id will return pointers to the same implementation object.

**Returns:** A shared pointer to the service instance.

**Parameters**

**`module`** `std::shared_ptr<Module>`

Is the shared object that owns the instance we wish to fetch

---

**`instance_id`** `const char *`

Names the specific object, usually expressed as a set of "name=value;..." pairs, as defined by the implementations themselves. This name is normally fetched by calling `Derived::locator_id(enumeration_metadata)`.

---

**`allow_null`** `bool` — default: false

The default value of `false` causes this routine to throw a std::runtime_error if the service cannot be found within the module; this would be expected to terminate the calling program. If the application wants to handle the error, pass in `true` here and get_service will return `nullptr` when this module doesn't provide the requested service.

---

### for_each_type_id \[#foreachtypeid]

```cpp showLineNumbers={false}
static bool hololink::module::Service<FrameMetadataInterfaceV1>::for_each_type_id(
    Callback &&cb
)
```

Iterate over every type_id supported by this instance.

The callback signature is `bool(const char*)` — returning false halts the walk; true continues. Iteration is depth-first, so you'll see the most specific implementation types first.

---

## Inner classes

### FrameMetadata

```cpp showLineNumbers={false}
struct hololink::module::FrameMetadataInterfaceV1::FrameMetadata
```

What the device reported about one received frame.

| Name            | Type       | Description                                                  |
| --------------- | ---------- | ------------------------------------------------------------ |
| `flags`         | `uint32_t` | Device-reported status of the frame.                         |
| `psn`           | `uint32_t` | Packet sequence number the frame ended on.                   |
| `crc`           | `uint32_t` | CRC the device computed over the frame data.                 |
| `frame_number`  | `uint16_t` | Frame counter, as the device numbers frames.                 |
| `timestamp_s`   | `uint64_t` | Device time when the frame's first sample data was received. |
| `timestamp_ns`  | `uint32_t` | Nanoseconds part of `timestamp_s`.                           |
| `bytes_written` | `uint64_t` | Frame data the device wrote, in bytes.                       |
| `metadata_s`    | `uint64_t` | Device time when the metadata block itself was sent.         |
| `metadata_ns`   | `uint32_t` | Nanoseconds part of `metadata_s`.                            |