iceoryx_binding_c/subscriber.h🔗

Classes🔗

	Name
struct	iox_sub_options_t options to be set for a subscriber

Types🔗

	Name
typedef struct cpp2c_Subscriber *	iox_sub_t Subscriber handle.

Functions🔗

	Name
void	iox_sub_options_init(iox_sub_options_t *const options) initialize subscriber options to default values
bool	iox_sub_options_is_initialized(const iox_sub_options_t *const options) check whether the subscriber options were initialized by iox_sub_options_init
iox_sub_t	iox_sub_init(iox_sub_storage_t * self, const char const service, const char const instance, const char const event, const iox_sub_options_t const options) initialize subscriber handle
void	iox_sub_deinit(iox_sub_t const self) deinitialize a subscriber handle
void	iox_sub_subscribe(iox_sub_t const self) subscribes to the service
void	iox_sub_unsubscribe(iox_sub_t const self) unsubscribes from a service
ENUM iox_SubscribeState	iox_sub_get_subscription_state(iox_sub_t const self) what is the subscription state?
ENUM iox_ChunkReceiveResult	iox_sub_take_chunk(iox_sub_t const self, const void **const userPayload) retrieve a received chunk
void	iox_sub_release_chunk(iox_sub_t const self, const void *const userPayload) release a previously acquired chunk (via iox_sub_take_chunk)
void	iox_sub_release_queued_chunks(iox_sub_t const self) release all chunks which are stored in the chunk queue
bool	iox_sub_has_chunks(iox_sub_t const self) are new chunks available?
bool	iox_sub_has_lost_chunks(iox_sub_t const self) are chunks lost?
iox_service_description_t	iox_sub_get_service_description(iox_sub_t const self) returns the service description of the subscriber

Types Documentation🔗

typedef iox_sub_t🔗

typedef struct cpp2c_Subscriber* iox_sub_t;

Subscriber handle.

Functions Documentation🔗

function iox_sub_options_init🔗

void iox_sub_options_init(
    iox_sub_options_t *const options
)

initialize subscriber options to default values

Parameters:

options pointer to options to be initialized, emit warning if it is a null pointer

Attention: This must always be called on a newly created options struct to prevent uninitialized values. The options may get extended in the future.

function iox_sub_options_is_initialized🔗

bool iox_sub_options_is_initialized(
    const iox_sub_options_t *const options
)

check whether the subscriber options were initialized by iox_sub_options_init

Parameters:

options pointer to options to be checked

Return: true if options are not null and were initialized, false otherwise

function iox_sub_init🔗

iox_sub_t iox_sub_init(
    iox_sub_storage_t * self,
    const char *const service,
    const char *const instance,
    const char *const event,
    const iox_sub_options_t *const options
)

initialize subscriber handle

Parameters:

self pointer to preallocated memory of size = sizeof(iox_sub_storage_t)
service serviceString
instance instanceString
event eventString
options subscriber options set by the user, if it is a null pointer default options are used

Return: handle of the subscriber

function iox_sub_deinit🔗

void iox_sub_deinit(
    iox_sub_t const self
)

deinitialize a subscriber handle

Parameters:

self the handle which should be removed

function iox_sub_subscribe🔗

void iox_sub_subscribe(
    iox_sub_t const self
)

subscribes to the service

Parameters:

self handle to the subscriber

function iox_sub_unsubscribe🔗

void iox_sub_unsubscribe(
    iox_sub_t const self
)

unsubscribes from a service

Parameters:

self handle to the subscriber

function iox_sub_get_subscription_state🔗

ENUM iox_SubscribeState iox_sub_get_subscription_state(
    iox_sub_t const self
)

what is the subscription state?

Parameters:

self handle to the subscriber

Return: SubscribeState_SUBSCRIBED when successfully subscribed otherwise an enum which describes the current state

function iox_sub_take_chunk🔗

ENUM iox_ChunkReceiveResult iox_sub_take_chunk(
    iox_sub_t const self,
    const void **const userPayload
)

retrieve a received chunk

Parameters:

self handle to the subscriber
userPayload pointer in which the pointer to the user-payload of the chunk is stored

Return: if a chunk could be received it returns ChunkReceiveResult_SUCCESS otherwise an enum which describes the error

function iox_sub_release_chunk🔗

void iox_sub_release_chunk(
    iox_sub_t const self,
    const void *const userPayload
)

release a previously acquired chunk (via iox_sub_take_chunk)

Parameters:

self handle to the subscriber
userPayload pointer to the user-payload of chunk which should be released

function iox_sub_release_queued_chunks🔗

void iox_sub_release_queued_chunks(
    iox_sub_t const self
)

release all chunks which are stored in the chunk queue

Parameters:

self handle to the subscriber

function iox_sub_has_chunks🔗

bool iox_sub_has_chunks(
    iox_sub_t const self
)

are new chunks available?

Parameters:

self handle to the subscriber

Return: true if there are chunks, otherwise false

function iox_sub_has_lost_chunks🔗

bool iox_sub_has_lost_chunks(
    iox_sub_t const self
)

are chunks lost?

Parameters:

self handle to the subscriber

Return: true if there are lost chunks due to overflowing queue, otherwise false

function iox_sub_get_service_description🔗

iox_service_description_t iox_sub_get_service_description(
    iox_sub_t const self
)

returns the service description of the subscriber

Parameters:

self handle to the subscriber

Return: the service description

Source code🔗

// Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
// Copyright (c) 2020 - 2022 by Apex.AI Inc. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
// SPDX-License-Identifier: Apache-2.0

#ifndef IOX_BINDING_C_SUBSCRIBER_H
#define IOX_BINDING_C_SUBSCRIBER_H

#include "iceoryx_binding_c/enums.h"
#include "iceoryx_binding_c/internal/c2cpp_binding.h"
#include "iceoryx_binding_c/service_description.h"
#include "iceoryx_binding_c/types.h"

typedef struct cpp2c_Subscriber* iox_sub_t;

typedef struct
{
    uint64_t queueCapacity;

    uint64_t historyRequest;

    const char* nodeName;

    bool subscribeOnCreate;

    ENUM iox_QueueFullPolicy queueFullPolicy;

    bool requirePublisherHistorySupport;

    uint64_t initCheck;
} iox_sub_options_t;

void iox_sub_options_init(iox_sub_options_t* const options);

bool iox_sub_options_is_initialized(const iox_sub_options_t* const options);

iox_sub_t iox_sub_init(iox_sub_storage_t* self,
                       const char* const service,
                       const char* const instance,
                       const char* const event,
                       const iox_sub_options_t* const options);

void iox_sub_deinit(iox_sub_t const self);

void iox_sub_subscribe(iox_sub_t const self);

void iox_sub_unsubscribe(iox_sub_t const self);

ENUM iox_SubscribeState iox_sub_get_subscription_state(iox_sub_t const self);

ENUM iox_ChunkReceiveResult iox_sub_take_chunk(iox_sub_t const self, const void** const userPayload);

void iox_sub_release_chunk(iox_sub_t const self, const void* const userPayload);

void iox_sub_release_queued_chunks(iox_sub_t const self);

bool iox_sub_has_chunks(iox_sub_t const self);

bool iox_sub_has_lost_chunks(iox_sub_t const self);

iox_service_description_t iox_sub_get_service_description(iox_sub_t const self);
#endif

Updated on 18 December 2023 at 13:02:35 CET