iceoryx_binding_c/client.h🔗

Classes🔗

	Name
struct	iox_client_options_t options to be set for a client

Types🔗

	Name
typedef CLASS UntypedClient *	iox_client_t client handle

Functions🔗

	Name
void	iox_client_options_init(iox_client_options_t * options) initialize client options to default values
bool	iox_client_options_is_initialized(const iox_client_options_t *const options) check whether the client options were initialized by iox_client_options_init
iox_client_t	iox_client_init(iox_client_storage_t * self, const char const service, const char const instance, const char const event, const iox_client_options_t const options) creates a client handle
void	iox_client_deinit(iox_client_t const self) removes a client handle
ENUM iox_AllocationResult	iox_client_loan_request(iox_client_t const self, void **const payload, const uint32_t payloadSize) allocates a request in the shared memory
ENUM iox_AllocationResult	iox_client_loan_aligned_request(iox_client_t const self, void **const payload, const uint32_t payloadSize, const uint32_t payloadAlignment) allocates a request in the shared memory with a custom alignment for the user-payload
void	iox_client_release_request(iox_client_t const self, void *const payload) releases ownership of a previously allocated loaned request without sending it
ENUM iox_ClientSendResult	iox_client_send(iox_client_t const self, void *const payload) sends a previously loaned request
void	iox_client_connect(iox_client_t const self) connects to the service
void	iox_client_disconnect(iox_client_t const self) disconnects from the service
ENUM iox_ConnectionState	iox_client_get_connection_state(iox_client_t const self) what is the connection state?
ENUM iox_ChunkReceiveResult	iox_client_take_response(iox_client_t const self, const void **const payload) retrieve a received respone
void	iox_client_release_response(iox_client_t const self, const void *const payload) release a previously acquired response (via iox_client_take_response)
void	iox_client_release_queued_responses(iox_client_t const self) release all responses which are stored in the chunk queue
bool	iox_client_has_responses(iox_client_t const self) are new responses available?
bool	iox_client_has_missed_responses(iox_client_t const self) were responses missed?
iox_service_description_t	iox_client_get_service_description(iox_client_t const self) returns the service description of the client

Types Documentation🔗

typedef iox_client_t🔗

typedef CLASS UntypedClient* iox_client_t;

client handle

Functions Documentation🔗

function iox_client_options_init🔗

void iox_client_options_init(
    iox_client_options_t * options
)

initialize client 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_client_options_is_initialized🔗

bool iox_client_options_is_initialized(
    const iox_client_options_t *const options
)

check whether the client options were initialized by iox_client_options_init

Parameters:

options pointer to options to be checked

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

function iox_client_init🔗

iox_client_t iox_client_init(
    iox_client_storage_t * self,
    const char *const service,
    const char *const instance,
    const char *const event,
    const iox_client_options_t *const options
)

creates a client handle

Parameters:

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

Return: handle of the client

function iox_client_deinit🔗

void iox_client_deinit(
    iox_client_t const self
)

removes a client handle

Parameters:

self the handle which should be removed

function iox_client_loan_request🔗

ENUM iox_AllocationResult iox_client_loan_request(
    iox_client_t const self,
    void **const payload,
    const uint32_t payloadSize
)

allocates a request in the shared memory

Parameters:

self handle of the client
payload pointer in which a pointer to the user-payload of the allocated chunk is stored
payloadSize user-payload size of the allocated request

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_client_loan_aligned_request

function iox_client_loan_aligned_request🔗

ENUM iox_AllocationResult iox_client_loan_aligned_request(
    iox_client_t const self,
    void **const payload,
    const uint32_t payloadSize,
    const uint32_t payloadAlignment
)

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

Parameters:

self handle of the client
payload pointer in which a pointer to the user-payload of the allocated request is stored
payloadSize user-payload size of the allocated request
payloadAlignment user-payload alignment of the allocated request

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

function iox_client_release_request🔗

void iox_client_release_request(
    iox_client_t const self,
    void *const payload
)

releases ownership of a previously allocated loaned request without sending it

Parameters:

self handle of the client
payload pointer to the user-payload of the loaned request which should be free'd

function iox_client_send🔗

ENUM iox_ClientSendResult iox_client_send(
    iox_client_t const self,
    void *const payload
)

sends a previously loaned request

Parameters:

self handle of the client
payload pointer to the user-payload of the request which should be send

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

function iox_client_connect🔗

void iox_client_connect(
    iox_client_t const self
)

connects to the service

Parameters:

self handle to the client

function iox_client_disconnect🔗

void iox_client_disconnect(
    iox_client_t const self
)

disconnects from the service

Parameters:

self handle to the client

function iox_client_get_connection_state🔗

ENUM iox_ConnectionState iox_client_get_connection_state(
    iox_client_t const self
)

what is the connection state?

Parameters:

self handle to the client

Return: ConnectionState_CONNECTED when successfully connected otherwise an enum which describes the current state

function iox_client_take_response🔗

ENUM iox_ChunkReceiveResult iox_client_take_response(
    iox_client_t const self,
    const void **const payload
)

retrieve a received respone

Parameters:

self handle to the client
payload pointer in which the pointer to the user-payload of the response is stored

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

function iox_client_release_response🔗

void iox_client_release_response(
    iox_client_t const self,
    const void *const payload
)

release a previously acquired response (via iox_client_take_response)

Parameters:

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

function iox_client_release_queued_responses🔗

void iox_client_release_queued_responses(
    iox_client_t const self
)

release all responses which are stored in the chunk queue

Parameters:

self handle to the client

function iox_client_has_responses🔗

bool iox_client_has_responses(
    iox_client_t const self
)

are new responses available?

Parameters:

self handle to the client

Return: true if there are responses, otherwise false

function iox_client_has_missed_responses🔗

bool iox_client_has_missed_responses(
    iox_client_t const self
)

were responses missed?

Parameters:

self handle to the client

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

function iox_client_get_service_description🔗

iox_service_description_t iox_client_get_service_description(
    iox_client_t const self
)

returns the service description of the client

Parameters:

self handle to the client

Return: the service description

Source code🔗

// Copyright (c) 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_CLIENT_H
#define IOX_BINDING_C_CLIENT_H

#include "iceoryx_binding_c/config.h"
#include "iceoryx_binding_c/enums.h"
#include "iceoryx_binding_c/service_description.h"
#include "iceoryx_binding_c/types.h"

typedef CLASS UntypedClient* iox_client_t;

typedef struct
{
    uint64_t responseQueueCapacity;

    char nodeName[IOX_CONFIG_NODE_NAME_SIZE];

    bool connectOnCreate;

    ENUM iox_QueueFullPolicy responseQueueFullPolicy;

    ENUM iox_ConsumerTooSlowPolicy serverTooSlowPolicy;

    uint64_t initCheck;
} iox_client_options_t;

void iox_client_options_init(iox_client_options_t* options);

bool iox_client_options_is_initialized(const iox_client_options_t* const options);

iox_client_t iox_client_init(iox_client_storage_t* self,
                             const char* const service,
                             const char* const instance,
                             const char* const event,
                             const iox_client_options_t* const options);

void iox_client_deinit(iox_client_t const self);

ENUM iox_AllocationResult iox_client_loan_request(iox_client_t const self,
                                                  void** const payload,
                                                  const uint32_t payloadSize);

ENUM iox_AllocationResult iox_client_loan_aligned_request(iox_client_t const self,
                                                          void** const payload,
                                                          const uint32_t payloadSize,
                                                          const uint32_t payloadAlignment);


void iox_client_release_request(iox_client_t const self, void* const payload);

ENUM iox_ClientSendResult iox_client_send(iox_client_t const self, void* const payload);

void iox_client_connect(iox_client_t const self);

void iox_client_disconnect(iox_client_t const self);

ENUM iox_ConnectionState iox_client_get_connection_state(iox_client_t const self);

ENUM iox_ChunkReceiveResult iox_client_take_response(iox_client_t const self, const void** const payload);

void iox_client_release_response(iox_client_t const self, const void* const payload);

void iox_client_release_queued_responses(iox_client_t const self);

bool iox_client_has_responses(iox_client_t const self);

bool iox_client_has_missed_responses(iox_client_t const self);

iox_service_description_t iox_client_get_service_description(iox_client_t const self);
#endif

Updated on 18 December 2023 at 13:11:43 CET