iceoryx_binding_c/server.h🔗

Classes🔗

	Name
struct	iox_server_options_t options to be set for a server

Types🔗

	Name
typedef CLASS UntypedServer *	iox_server_t server handle

Functions🔗

	Name
void	iox_server_options_init(iox_server_options_t *const options) initialize server options to default values
bool	iox_server_options_is_initialized(const iox_server_options_t *const options) check whether the server options were initialized by iox_server_options_init
iox_server_t	iox_server_init(iox_server_storage_t * self, const char const service, const char const instance, const char const event, const iox_server_options_t const options) creates a server handle
void	iox_server_deinit(iox_server_t const self) removes a server handle
ENUM iox_ServerRequestResult	iox_server_take_request(iox_server_t const self, const void **const payload) retrieve a received request
void	iox_server_release_request(iox_server_t const self, const void *const payload) release a previously acquired request (via iox_server_take_request)
ENUM iox_AllocationResult	iox_server_loan_response(iox_server_t const self, const void const requestPayload, void *const payload, const uint32_t payloadSize) allocates a response in the shared memory
ENUM iox_AllocationResult	iox_server_loan_aligned_response(iox_server_t const self, const void const requestPayload, void *const payload, const uint32_t payloadSize, const uint32_t payloadAlignment) allocates a response in the shared memory
ENUM iox_ServerSendResult	iox_server_send(iox_server_t const self, void *const payload) sends a previously loaned response
void	iox_server_release_response(iox_server_t const self, void *const payload) releases ownership of a previously allocated loaned response without sending it
iox_service_description_t	iox_server_get_service_description(iox_server_t const self) returns the service description of the server
void	iox_server_offer(iox_server_t const self) offers the servers service
void	iox_server_stop_offer(iox_server_t const self) stops offering the servers service
bool	iox_server_is_offered(iox_server_t const self) is the server currently offering?
bool	iox_server_has_clients(iox_server_t const self) are clients connected to the server?
bool	iox_server_has_requests(iox_server_t const self) are requests from clients available?
bool	iox_server_has_missed_requests(iox_server_t const self) were requests missed?
void	iox_server_release_queued_requests(iox_server_t const self) release a previously acquired request (via iox_server_take_request)

Types Documentation🔗

typedef iox_server_t🔗

typedef CLASS UntypedServer* iox_server_t;

server handle

Functions Documentation🔗

function iox_server_options_init🔗

void iox_server_options_init(
    iox_server_options_t *const options
)

initialize server 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_server_options_is_initialized🔗

bool iox_server_options_is_initialized(
    const iox_server_options_t *const options
)

check whether the server options were initialized by iox_server_options_init

Parameters:

options pointer to options to be checked

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

function iox_server_init🔗

iox_server_t iox_server_init(
    iox_server_storage_t * self,
    const char *const service,
    const char *const instance,
    const char *const event,
    const iox_server_options_t *const options
)

creates a server handle

Parameters:

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

Return: handle of the server

function iox_server_deinit🔗

void iox_server_deinit(
    iox_server_t const self
)

removes a server handle

Parameters:

self the handle which should be removed

function iox_server_take_request🔗

ENUM iox_ServerRequestResult iox_server_take_request(
    iox_server_t const self,
    const void **const payload
)

retrieve a received request

Parameters:

self handle to the server
payload pointer in which the pointer to the user-payload of the request is stored

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

function iox_server_release_request🔗

void iox_server_release_request(
    iox_server_t const self,
    const void *const payload
)

release a previously acquired request (via iox_server_take_request)

Parameters:

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

function iox_server_loan_response🔗

ENUM iox_AllocationResult iox_server_loan_response(
    iox_server_t const self,
    const void *const requestPayload,
    void **const payload,
    const uint32_t payloadSize
)

allocates a response in the shared memory

Parameters:

self handle of the server
requestPayload pointer to the payload of the received request
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_server_loan_aligned_response

function iox_server_loan_aligned_response🔗

ENUM iox_AllocationResult iox_server_loan_aligned_response(
    iox_server_t const self,
    const void *const requestPayload,
    void **const payload,
    const uint32_t payloadSize,
    const uint32_t payloadAlignment
)

allocates a response in the shared memory

Parameters:

self handle of the server
requestPayload pointer to the payload of the received request
payload pointer in which a pointer to the user-payload of the allocated chunk 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_server_send🔗

ENUM iox_ServerSendResult iox_server_send(
    iox_server_t const self,
    void *const payload
)

sends a previously loaned response

Parameters:

self handle of the server
payload pointer to the user-payload of the response which should be send

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

function iox_server_release_response🔗

void iox_server_release_response(
    iox_server_t const self,
    void *const payload
)

releases ownership of a previously allocated loaned response without sending it

Parameters:

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

function iox_server_get_service_description🔗

iox_service_description_t iox_server_get_service_description(
    iox_server_t const self
)

returns the service description of the server

Parameters:

self handle to the server

Return: the service description

function iox_server_offer🔗

void iox_server_offer(
    iox_server_t const self
)

offers the servers service

Parameters:

self handle to the server

function iox_server_stop_offer🔗

void iox_server_stop_offer(
    iox_server_t const self
)

stops offering the servers service

Parameters:

self handle to the server

function iox_server_is_offered🔗

bool iox_server_is_offered(
    iox_server_t const self
)

is the server currently offering?

Parameters:

self handle to the server

Return: true if the server is offering, otherwise false

function iox_server_has_clients🔗

bool iox_server_has_clients(
    iox_server_t const self
)

are clients connected to the server?

Parameters:

self handle to the server

Return: true if the server has connected clients, otherwise false

function iox_server_has_requests🔗

bool iox_server_has_requests(
    iox_server_t const self
)

are requests from clients available?

Parameters:

self handle to the server

Return: true if the requests are available to take, otherwise false

function iox_server_has_missed_requests🔗

bool iox_server_has_missed_requests(
    iox_server_t const self
)

were requests missed?

Parameters:

self handle to the server

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

function iox_server_release_queued_requests🔗

void iox_server_release_queued_requests(
    iox_server_t const self
)

release a previously acquired request (via iox_server_take_request)

Parameters:

self handle to the server

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_SERVER_H
#define IOX_BINDING_C_SERVER_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 UntypedServer* iox_server_t;

typedef struct
{
    uint64_t requestQueueCapacity;

    char nodeName[IOX_CONFIG_NODE_NAME_SIZE];

    bool offerOnCreate;

    ENUM iox_QueueFullPolicy requestQueueFullPolicy;

    ENUM iox_ConsumerTooSlowPolicy clientTooSlowPolicy;

    uint64_t initCheck;
} iox_server_options_t;

void iox_server_options_init(iox_server_options_t* const options);

bool iox_server_options_is_initialized(const iox_server_options_t* const options);

iox_server_t iox_server_init(iox_server_storage_t* self,
                             const char* const service,
                             const char* const instance,
                             const char* const event,
                             const iox_server_options_t* const options);

void iox_server_deinit(iox_server_t const self);

ENUM iox_ServerRequestResult iox_server_take_request(iox_server_t const self, const void** const payload);

void iox_server_release_request(iox_server_t const self, const void* const payload);

ENUM iox_AllocationResult iox_server_loan_response(iox_server_t const self,
                                                   const void* const requestPayload,
                                                   void** const payload,
                                                   const uint32_t payloadSize);

ENUM iox_AllocationResult iox_server_loan_aligned_response(iox_server_t const self,
                                                           const void* const requestPayload,
                                                           void** const payload,
                                                           const uint32_t payloadSize,
                                                           const uint32_t payloadAlignment);

ENUM iox_ServerSendResult iox_server_send(iox_server_t const self, void* const payload);

void iox_server_release_response(iox_server_t const self, void* const payload);

iox_service_description_t iox_server_get_service_description(iox_server_t const self);

void iox_server_offer(iox_server_t const self);

void iox_server_stop_offer(iox_server_t const self);

bool iox_server_is_offered(iox_server_t const self);

bool iox_server_has_clients(iox_server_t const self);

bool iox_server_has_requests(iox_server_t const self);

bool iox_server_has_missed_requests(iox_server_t const self);

void iox_server_release_queued_requests(iox_server_t const self);

#endif

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