Skip to content

iceoryx_binding_c/publisher.h🔗

Classes🔗

Name
struct iox_pub_options_t
options to be set for a publisher

Types🔗

Name
typedef struct cpp2c_Publisher * iox_pub_t
publisher handle

Functions🔗

Name
void iox_pub_options_init(iox_pub_options_t * options)
initialize publisher options to default values
bool iox_pub_options_is_initialized(const iox_pub_options_t *const options)
check whether the publisher options were initialized by iox_pub_options_init
iox_pub_t iox_pub_init(iox_pub_storage_t * self, const char const service, const char const instance, const char const event, const iox_pub_options_t const options)
creates a publisher handle
void iox_pub_deinit(iox_pub_t const self)
removes a publisher handle
ENUM iox_AllocationResult iox_pub_loan_chunk(iox_pub_t const self, void **const userPayload, const uint32_t userPayloadSize)
allocates a chunk in the shared memory
ENUM iox_AllocationResult iox_pub_loan_aligned_chunk(iox_pub_t const self, void **const userPayload, const uint32_t userPayloadSize, const uint32_t userPayloadAlignment)
allocates a chunk in the shared memory with a custom alignment for the user-payload
ENUM iox_AllocationResult iox_pub_loan_aligned_chunk_with_user_header(iox_pub_t const self, void **const userPayload, const uint32_t userPayloadSize, const uint32_t userPayloadAlignment, const uint32_t userHeaderSize, const uint32_t userHeaderAlignment)
allocates a chunk in the shared memory with a section for the user-header and a custom alignment for the user-payload
void iox_pub_release_chunk(iox_pub_t const self, void *const userPayload)
releases ownership of a previously allocated chunk without sending it
void iox_pub_publish_chunk(iox_pub_t const self, void *const userPayload)
sends a previously allocated chunk
void iox_pub_offer(iox_pub_t const self)
offers the service
void iox_pub_stop_offer(iox_pub_t const self)
stop offering the service
bool iox_pub_is_offered(iox_pub_t const self)
is the service still offered
bool iox_pub_has_subscribers(iox_pub_t const self)
does the service have subscribers
iox_service_description_t iox_pub_get_service_description(iox_pub_t const self)
returns the service description of the publisher

Types Documentation🔗

typedef iox_pub_t🔗

typedef struct cpp2c_Publisher* iox_pub_t;

publisher handle

Functions Documentation🔗

function iox_pub_options_init🔗

void iox_pub_options_init(
    iox_pub_options_t * options
)

initialize publisher 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_pub_options_is_initialized🔗

bool iox_pub_options_is_initialized(
    const iox_pub_options_t *const options
)

check whether the publisher options were initialized by iox_pub_options_init

Parameters:

  • options pointer to options to be checked

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

function iox_pub_init🔗

iox_pub_t iox_pub_init(
    iox_pub_storage_t * self,
    const char *const service,
    const char *const instance,
    const char *const event,
    const iox_pub_options_t *const options
)

creates a publisher handle

Parameters:

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

Return: handle of the publisher

function iox_pub_deinit🔗

void iox_pub_deinit(
    iox_pub_t const self
)

removes a publisher handle

Parameters:

  • self the handle which should be removed

function iox_pub_loan_chunk🔗

ENUM iox_AllocationResult iox_pub_loan_chunk(
    iox_pub_t const self,
    void **const userPayload,
    const uint32_t userPayloadSize
)

allocates a chunk in the shared memory

Parameters:

  • self handle of the publisher
  • userPayload pointer in which a pointer to the user-payload of the allocated chunk is stored
  • userPayloadSize user-payload size of the allocated chunk

Return: on success it returns AllocationResult_SUCCESS otherwise a value which describes the error

Note: for the user-payload alignment IOX_C_CHUNK_DEFAULT_USER_PAYLOAD_ALIGNMENT is used for a custom user-payload alignment please use iox_pub_loan_aligned_chunk

function iox_pub_loan_aligned_chunk🔗

ENUM iox_AllocationResult iox_pub_loan_aligned_chunk(
    iox_pub_t const self,
    void **const userPayload,
    const uint32_t userPayloadSize,
    const uint32_t userPayloadAlignment
)

allocates a chunk in the shared memory with a custom alignment for the user-payload

Parameters:

  • self handle of the publisher
  • userPayload pointer in which a pointer to the user-payload of the allocated chunk is stored
  • userPayloadSize user-payload size of the allocated chunk
  • userPayloadAlignment user-payload alignment of the allocated chunk

Return: on success it returns AllocationResult_SUCCESS otherwise a value which describes the error

function iox_pub_loan_aligned_chunk_with_user_header🔗

ENUM iox_AllocationResult iox_pub_loan_aligned_chunk_with_user_header(
    iox_pub_t const self,
    void **const userPayload,
    const uint32_t userPayloadSize,
    const uint32_t userPayloadAlignment,
    const uint32_t userHeaderSize,
    const uint32_t userHeaderAlignment
)

allocates a chunk in the shared memory with a section for the user-header and a custom alignment for the user-payload

Parameters:

  • self handle of the publisher
  • userPayload pointer in which a pointer to the user-payload of the allocated chunk is stored
  • userPayloadSize user-payload size of the allocated chunk
  • userPayloadAlignment user-payload alignment of the allocated chunk
  • userHeaderSize user-header size of the allocated chunk
  • userHeaderAlignment user-header alignment of the allocated chunk

Return: on success it returns AllocationResult_SUCCESS otherwise a value which describes the error

function iox_pub_release_chunk🔗

void iox_pub_release_chunk(
    iox_pub_t const self,
    void *const userPayload
)

releases ownership of a previously allocated chunk without sending it

Parameters:

  • self handle of the publisher
  • userPayload pointer to the user-payload of the chunk which should be free'd

function iox_pub_publish_chunk🔗

void iox_pub_publish_chunk(
    iox_pub_t const self,
    void *const userPayload
)

sends a previously allocated chunk

Parameters:

  • self handle of the publisher
  • userPayload pointer to the user-payload of the chunk which should be send

function iox_pub_offer🔗

void iox_pub_offer(
    iox_pub_t const self
)

offers the service

Parameters:

  • self handle of the publisher

function iox_pub_stop_offer🔗

void iox_pub_stop_offer(
    iox_pub_t const self
)

stop offering the service

Parameters:

  • self handle of the publisher

function iox_pub_is_offered🔗

bool iox_pub_is_offered(
    iox_pub_t const self
)

is the service still offered

Parameters:

  • self handle of the publisher

Return: true is the service is offered otherwise false

function iox_pub_has_subscribers🔗

bool iox_pub_has_subscribers(
    iox_pub_t const self
)

does the service have subscribers

Parameters:

  • self handle of the publisher

Return: true if there are subscribers otherwise false

function iox_pub_get_service_description🔗

iox_service_description_t iox_pub_get_service_description(
    iox_pub_t const self
)

returns the service description of the publisher

Parameters:

  • self handle to the publisher

Return: the service description

Source code🔗

// Copyright (c) 2020 by Robert Bosch GmbH. All rights reserved.
// Copyright (c) 2020 - 2021 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_PUBLISHER_H
#define IOX_BINDING_C_PUBLISHER_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_Publisher* iox_pub_t;

typedef struct
{
    uint64_t historyCapacity;

    const char* nodeName;

    bool offerOnCreate;

    ENUM iox_ConsumerTooSlowPolicy subscriberTooSlowPolicy;

    uint64_t initCheck;
} iox_pub_options_t;

void iox_pub_options_init(iox_pub_options_t* options);

bool iox_pub_options_is_initialized(const iox_pub_options_t* const options);

iox_pub_t iox_pub_init(iox_pub_storage_t* self,
                       const char* const service,
                       const char* const instance,
                       const char* const event,
                       const iox_pub_options_t* const options);

void iox_pub_deinit(iox_pub_t const self);

ENUM iox_AllocationResult iox_pub_loan_chunk(iox_pub_t const self,
                                             void** const userPayload,
                                             const uint32_t userPayloadSize);

ENUM iox_AllocationResult iox_pub_loan_aligned_chunk(iox_pub_t const self,
                                                     void** const userPayload,
                                                     const uint32_t userPayloadSize,
                                                     const uint32_t userPayloadAlignment);

ENUM iox_AllocationResult iox_pub_loan_aligned_chunk_with_user_header(iox_pub_t const self,
                                                                      void** const userPayload,
                                                                      const uint32_t userPayloadSize,
                                                                      const uint32_t userPayloadAlignment,
                                                                      const uint32_t userHeaderSize,
                                                                      const uint32_t userHeaderAlignment);

void iox_pub_release_chunk(iox_pub_t const self, void* const userPayload);

void iox_pub_publish_chunk(iox_pub_t const self, void* const userPayload);

void iox_pub_offer(iox_pub_t const self);

void iox_pub_stop_offer(iox_pub_t const self);

bool iox_pub_is_offered(iox_pub_t const self);

bool iox_pub_has_subscribers(iox_pub_t const self);

iox_service_description_t iox_pub_get_service_description(iox_pub_t const self);
#endif

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