Group msg¶

Modules > msg

Public Functions¶

Public Functions Documentation¶

function dp_mean_power¶

Mean power of a complex sample block, normalised to full scale.

double dp_mean_power (
    dp_sample_type_t format,
    const void * data,
    size_t n
) 

mean(|x|^2), with the integer formats divided by dp_format_full_scale() first so the answer means the same thing whatever the format is — 10*log10() of it is dBFS in every case. The frame-level dp_msg_mean_power() is this over a received message.

Parameters:

• format Sample format of data.
• data n complex samples, interleaved for an integer format.
• n Sample count.

Returns:

Mean power, or 0 for a NULL pointer, an empty block, or a format this build does not know.

function dp_msg_ack¶

Acknowledge a message on a durable (JetStream) consumer.

int dp_msg_ack (
    dp_msg_t * msg
) 

For the resilient NATS work-queue tier (a nats:// Pull consumer), delivery is at-least-once: a message stays pending until acked, and is redelivered if the consumer dies before acking. Call this once the message has been fully processed, then dp_msg_free().

A no-op (returns DP_OK) for transports without acks — NATS core PUB/SUB and reassembled chunked frames — so callers can ack unconditionally.

Parameters:

• msg Message handle returned by a recv function.

Returns:

DP_OK on success, negative error code on failure.

function dp_msg_data¶

Return a pointer to the raw sample data inside the message.

void * dp_msg_data (
    dp_msg_t * msg
) 

Parameters:

• msg Message handle returned by a recv function.

Returns:

Pointer to contiguous sample data (valid until dp_msg_free).

function dp_msg_free¶

Free a message handle and release the underlying buffer.

void dp_msg_free (
    dp_msg_t * msg
) 

Parameters:

• msg Message handle (may be NULL).

function dp_msg_kind¶

What the message's payload IS (dp_frame_kind_t).

dp_frame_kind_t dp_msg_kind (
    dp_msg_t * msg
) 

Ask this before dp_msg_sample_type(): a telemetry frame's format field is 0, because BLUE has no code for a record stream.

Parameters:

• msg Message handle.

Returns:

The frame's kind, or DP_KIND_IQ for a NULL handle.

function dp_msg_mean_power¶

Mean power of a received I/Q frame, normalised to full scale.

double dp_msg_mean_power (
    dp_msg_t * msg
) 

dp_mean_power() over the frame's own samples: the format and the count come from its header, so a subscriber that takes whatever arrives can compare frames without branching on the type. 10*log10() of it is dBFS.

Exists because every consumer was writing this loop: the C receiver example carried one copy per wire type and a switch to pick between them, which is the same duplication the library forbids internally.

Parameters:

• msg Message handle from a recv.

Returns:

Mean power, or 0 for a NULL handle, an empty frame, or a non-I/Q kind (telemetry records are not samples).

function dp_msg_num_samples¶

Return the number of complex samples in the message.

size_t dp_msg_num_samples (
    dp_msg_t * msg
) 

Parameters:

• msg Message handle.

Returns:

Number of samples (header num_samples).

function dp_msg_sample_type¶

Return the sample type of the message.

dp_sample_type_t dp_msg_sample_type (
    dp_msg_t * msg
) 

Parameters:

• msg Message handle.

Returns:

Sample type enum value.

function dp_msg_size¶

Return the byte size of the sample data.

size_t dp_msg_size (
    dp_msg_t * msg
) 

Parameters:

• msg Message handle.

Returns:

Total data bytes.