Lely core libraries  2.2.5
val.h File Reference

This header file is part of the CANopen library; it contains the CANopen value declarations. More...

#include <lely/co/type.h>
#include <float.h>
#include <stddef.h>
#include <lely/co/def/type.def>
Include dependency graph for val.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

union  co_val
 A union of the CANopen static data types. More...
 

Macros

#define CO_BOOLEAN_MIN   0
 The minimum value of a boolean truth value (false).
 
#define CO_BOOLEAN_MAX   1
 The maximum value of a boolean truth value (true).
 
#define CO_INTEGER8_MIN   INT8_MIN
 The minimum value of an 8-bit signed integer.
 
#define CO_INTEGER8_MAX   INT8_MAX
 The maximum value of an 8-bit signed integer.
 
#define CO_INTEGER16_MIN   INT16_MIN
 The minimum value of a 16-bit signed integer.
 
#define CO_INTEGER16_MAX   INT16_MAX
 The maximum value of a 16-bit signed integer.
 
#define CO_INTEGER32_MIN   INT32_MIN
 The minimum value of a 32-bit signed integer.
 
#define CO_INTEGER32_MAX   INT32_MAX
 The maximum value of a 32-bit signed integer.
 
#define CO_UNSIGNED8_MIN   0
 The minimum value of an 8-bit unsigned integer.
 
#define CO_UNSIGNED8_MAX   UINT8_MAX
 The maximum value of an 8-bit unsigned integer.
 
#define CO_UNSIGNED16_MIN   0
 The minimum value of a 16-bit unsigned integer.
 
#define CO_UNSIGNED16_MAX   UINT16_MAX
 The maximum value of a 16-bit unsigned integer.
 
#define CO_UNSIGNED32_MIN   0
 The minimum value of a 32-bit unsigned integer.
 
#define CO_UNSIGNED32_MAX   UINT32_MAX
 The maximum value of a 32-bit unsigned integer.
 
#define CO_REAL32_MIN   (-FLT_MAX)
 The minimum value of a 32-bit IEEE-754 floating-point number.
 
#define CO_REAL32_MAX   FLT_MAX
 The maximum value of a 32-bit IEEE-754 floating-point number.
 
#define CO_TIME_OF_DAY_MIN
 The minimum value of a 48-bit structure representing the absolute time.
 
#define CO_TIME_OF_DAY_MAX
 The maximum value of a 48-bit structure representing the absolute time.
 
#define CO_TIME_DIFF_MIN   CO_TIME_OF_DAY_MIN
 The minimum value of a 48-bit structure representing a time difference.
 
#define CO_TIME_DIFF_MAX   CO_TIME_OF_DAY_MAX
 The maximum value of a 48-bit structure representing a time difference.
 
#define CO_INTEGER24_MIN   (-INT32_C(0x00800000))
 The minimum value of a 24-bit signed integer (encoded as an int32_t).
 
#define CO_INTEGER24_MAX   INT32_C(0x007fffff)
 The maximum value of a 24-bit signed integer (encoded as an int32_t).
 
#define CO_REAL64_MIN   (-DBL_MAX)
 The minimum value of a 64-bit IEEE-754 floating-point number.
 
#define CO_REAL64_MAX   DBL_MAX
 The maximum value of a 64-bit IEEE-754 floating-point number.
 
#define CO_INTEGER40_MIN   (-INT64_C(0x0000008000000000))
 The minimum value of a 40-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER40_MAX   INT64_C(0x0000007fffffffff)
 The maximum value of a 40-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER48_MIN   (-INT64_C(0x0000800000000000))
 The minimum value of a 48-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER48_MAX   INT64_C(0x00007fffffffffff)
 The maximum value of a 48-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER56_MIN   (-INT64_C(0x0080000000000000))
 The minimum value of a 56-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER56_MAX   INT64_C(0x007fffffffffffff)
 The maximum value of a 56-bit signed integer (encoded as an int64_t).
 
#define CO_INTEGER64_MIN   INT64_MIN
 The minimum value of a 64-bit signed integer.
 
#define CO_INTEGER64_MAX   INT64_MAX
 The maximum value of a 64-bit signed integer.
 
#define CO_UNSIGNED24_MIN   0
 The minimum value of a 24-bit unsigned integer (encoded as a uint32_t).
 
#define CO_UNSIGNED24_MAX   UINT32_C(0x00ffffff)
 The maximum value of a 24-bit unsigned integer (encoded as a uint32_t).
 
#define CO_UNSIGNED40_MIN   0
 The minimum value of a 40-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED40_MAX   UINT64_C(0x000000ffffffffff)
 The maximum value of a 40-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED48_MIN   0
 The minimum value of a 48-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED48_MAX   UINT64_C(0x0000ffffffffffff)
 The maximum value of a 48-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED56_MIN   0
 The minimum value of a 56-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED56_MAX   UINT64_C(0x00ffffffffffffff)
 The maximum value of a 56-bit unsigned integer (encoded as a uint64_t).
 
#define CO_UNSIGNED64_MIN   0
 The minimum value of a 64-bit unsigned integer.
 
#define CO_UNSIGNED64_MAX   UINT64_MAX
 The maximum value of a 64-bit unsigned integer.
 
#define CO_VISIBLE_STRING_C(c)
 Converts a visible string literal to a CANopen array.
 
#define CO_OCTET_STRING_C(c)
 Converts an octet string literal to a CANopen array.
 
#define CO_UNICODE_STRING_C(...)   _CO_UNICODE_STRING_C(_CO_ARRAY(__VA_ARGS__))
 Converts a (16-bit) Unicode string literal to a CANopen array.
 
#define CO_DOMAIN_C(type, ...)   _CO_DOMAIN_C(type, _CO_ARRAY(__VA_ARGS__))
 Converts an array literal with elements of type type to a CANopen array.
 

Functions

int co_val_init (co_unsigned16_t type, void *val)
 Initializes a value of the specified data type to zero. More...
 
int co_val_init_min (co_unsigned16_t type, void *val)
 Initializes a value of the specified data type with its lower limit. More...
 
int co_val_init_max (co_unsigned16_t type, void *val)
 Initializes a value of the specified data type with its upper limit. More...
 
int co_val_init_vs (char **val, const char *vs)
 Initializes an array of visible characters (CO_DEFTYPE_VISIBLE_STRING). More...
 
int co_val_init_vs_n (char **val, const char *vs, size_t n)
 Initializes an array of visible characters (CO_DEFTYPE_VISIBLE_STRING). More...
 
int co_val_init_os (uint_least8_t **val, const uint_least8_t *os, size_t n)
 Initializes an array of octets (CO_DEFTYPE_OCTET_STRING). More...
 
int co_val_init_us (char16_t **val, const char16_t *us)
 Initializes an array of (16-bit) Unicode characters (CO_DEFTYPE_UNICODE_STRING). More...
 
int co_val_init_us_n (char16_t **val, const char16_t *us, size_t n)
 Initializes an array of (16-bit) Unicode characters (CO_DEFTYPE_UNICODE_STRING). More...
 
int co_val_init_dom (void **val, const void *dom, size_t n)
 Initializes an arbitrary large block of data (CO_DEFTYPE_DOMAIN). More...
 
void co_val_fini (co_unsigned16_t type, void *val)
 Finalizes a value of the specified data type. More...
 
const void * co_val_addressof (co_unsigned16_t type, const void *val)
 Returns the address of the first byte in a value of the specified data type. More...
 
size_t co_val_sizeof (co_unsigned16_t type, const void *val)
 Returns the size (in bytes) of a value of the specified data type. More...
 
size_t co_val_make (co_unsigned16_t type, void *val, const void *ptr, size_t n)
 Constructs a value of the specified data type. More...
 
size_t co_val_copy (co_unsigned16_t type, void *dst, const void *src)
 Copies one value to another. More...
 
size_t co_val_move (co_unsigned16_t type, void *dst, void *src)
 Moves one value to another. More...
 
int co_val_cmp (co_unsigned16_t type, const void *v1, const void *v2)
 Compares two values of the specified data type. More...
 
size_t co_val_read (co_unsigned16_t type, void *val, const uint_least8_t *begin, const uint_least8_t *end)
 Reads a value of the specified data type from a memory buffer. More...
 
co_unsigned32_t co_val_read_sdo (co_unsigned16_t type, void *val, const void *ptr, size_t n)
 Reads a value of the specified data type from an SDO buffer. More...
 
size_t co_val_write (co_unsigned16_t type, const void *val, uint_least8_t *begin, uint_least8_t *end)
 Writes a value of the specified data type to a memory buffer. More...
 
size_t co_val_lex (co_unsigned16_t type, void *val, const char *begin, const char *end, struct floc *at)
 Lexes a value of the specified data type from a memory buffer. More...
 
size_t co_val_print (co_unsigned16_t type, const void *val, char **pbegin, char *end)
 Prints a value of the specified data type to a memory buffer. More...
 

Detailed Description

This header file is part of the CANopen library; it contains the CANopen value declarations.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

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.

Definition in file val.h.

Function Documentation

◆ co_val_init()

int co_val_init ( co_unsigned16_t  type,
void *  val 
)

Initializes a value of the specified data type to zero.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be initialized. In the case of strings or domains, this MUST be the address of pointer.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 122 of file val.c.

◆ co_val_init_min()

int co_val_init_min ( co_unsigned16_t  type,
void *  val 
)

Initializes a value of the specified data type with its lower limit.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be initialized. In the case of strings or domains, this MUST be the address of pointer, which will be set to NULL.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 139 of file val.c.

◆ co_val_init_max()

int co_val_init_max ( co_unsigned16_t  type,
void *  val 
)

Initializes a value of the specified data type with its upper limit.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be initialized. In the case of strings or domains, this MUST be the address of pointer, which will be set to NULL.
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 156 of file val.c.

◆ co_val_init_vs()

int co_val_init_vs ( char **  val,
const char *  vs 
)

Initializes an array of visible characters (CO_DEFTYPE_VISIBLE_STRING).

Parameters
valthe address of a pointer. On success, *val points to the first character in the string.
vsa pointer to the (null-terminated) string with which *val should be initialized (can be NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 173 of file val.c.

◆ co_val_init_vs_n()

int co_val_init_vs_n ( char **  val,
const char *  vs,
size_t  n 
)

Initializes an array of visible characters (CO_DEFTYPE_VISIBLE_STRING).

Parameters
valthe address of a pointer. On success, *val points to the first character in the string.
vsa pointer to the string with which *val should be initialized (can be NULL).
nthe number of characters in the value to be created (excluding the terminating null byte) and the maximum number of characters to copy from vs (unless vs is NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 186 of file val.c.

◆ co_val_init_os()

int co_val_init_os ( uint_least8_t **  val,
const uint_least8_t *  os,
size_t  n 
)

Initializes an array of octets (CO_DEFTYPE_OCTET_STRING).

Parameters
valthe address of a pointer. On success, *val points to the first octet in the string.
osa pointer to the array of octets with which *val should be initialized (can be NULL).
nthe number of octets in the value to be created (and the number of octets at os unless os is NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 205 of file val.c.

◆ co_val_init_us()

int co_val_init_us ( char16_t **  val,
const char16_t *  us 
)

Initializes an array of (16-bit) Unicode characters (CO_DEFTYPE_UNICODE_STRING).

Parameters
valthe address of a pointer. On success, *val points to the first character in the string.
usa pointer to the (null-terminated) string with which *val should be initialized (can be NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 224 of file val.c.

◆ co_val_init_us_n()

int co_val_init_us_n ( char16_t **  val,
const char16_t *  us,
size_t  n 
)

Initializes an array of (16-bit) Unicode characters (CO_DEFTYPE_UNICODE_STRING).

Parameters
valthe address of a pointer. On success, *val points to the first character in the string.
usa pointer to the string with which *val should be initialized (can be NULL).
nthe number of (16-bit) Unicode characters in the value to be created (excluding the terminating null bytes) and the maximum number of characters to copy from us (unless us is NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 237 of file val.c.

◆ co_val_init_dom()

int co_val_init_dom ( void **  val,
const void *  dom,
size_t  n 
)

Initializes an arbitrary large block of data (CO_DEFTYPE_DOMAIN).

Parameters
valthe address of a pointer. On success, *val points to the first byte.
doma pointer to the bytes with which *val should be initialized (can be NULL).
nthe number of bytes in the value to be created (and the number of bytes at dom unless dom is NULL).
Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_fini()

Definition at line 256 of file val.c.

◆ co_val_fini()

void co_val_fini ( co_unsigned16_t  type,
void *  val 
)

Finalizes a value of the specified data type.

It is safe to invoke this function multiple times on the same value.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be finalized (can be NULL). In the case of strings or domains, this MUST be the address of pointer.
See also
co_val_init()

Definition at line 275 of file val.c.

◆ co_val_addressof()

const void* co_val_addressof ( co_unsigned16_t  type,
const void *  val 
)

Returns the address of the first byte in a value of the specified data type.

In the case of strings or domains, this is the address of the first byte in the array.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value (can be NULL). In the case of strings or domains, this MUST be the address of pointer.
See also
co_val_sizeof()

Definition at line 286 of file val.c.

◆ co_val_sizeof()

size_t co_val_sizeof ( co_unsigned16_t  type,
const void *  val 
)

Returns the size (in bytes) of a value of the specified data type.

In the case of strings or domains, this is the number of bytes in the array.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value (can be NULL). In the case of strings or domains, this MUST be the address of pointer.
See also
co_val_addressof()

Definition at line 295 of file val.c.

◆ co_val_make()

size_t co_val_make ( co_unsigned16_t  type,
void *  val,
const void *  ptr,
size_t  n 
)

Constructs a value of the specified data type.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be constructed. In the case of strings or domains, this MUST be the address of pointer. Note that this value is not finalized before the copy is performed.
ptra pointer to the bytes to be copied. In case of strings or domains, ptr MUST point to the first byte in the array.
nthe number of bytes at ptr. In case of strings, n SHOULD exclude the terminating null byte(s).
Returns
the number of bytes copied (i.e., n), or 0 on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 308 of file val.c.

◆ co_val_copy()

size_t co_val_copy ( co_unsigned16_t  type,
void *  dst,
const void *  src 
)

Copies one value to another.

In case of strings or domains, this function performs a deep copy (i.e, it copies the array).

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
dsta pointer to the destination value. In the case of strings or domains, this MUST be the address of pointer. Note that this value is not finalized before the copy is performed.
srca pointer to the source value. In the case of strings or domains, this MUST be the address of pointer.
Returns
the number of bytes copied (i.e., the result of co_val_sizeof(type, src)), or 0 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_move()

Definition at line 344 of file val.c.

◆ co_val_move()

size_t co_val_move ( co_unsigned16_t  type,
void *  dst,
void *  src 
)

Moves one value to another.

In case of strings or domains, this function performs a shallow copy (i.e., it copies the pointer to the array).

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
dsta pointer to the destination value. In the case of strings or domains, this MUST be the address of pointer. Note that this value is not finalized before the move is performed.
srca pointer to the source value. In the case of strings or domains, this MUST be the address of pointer (which is set to NULL on exit).
Returns
the number of bytes copied (i.e., the result of co_type_sizeof(type)), or 0 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_copy()

Definition at line 382 of file val.c.

◆ co_val_cmp()

int co_val_cmp ( co_unsigned16_t  type,
const void *  v1,
const void *  v2 
)

Compares two values of the specified data type.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
v1a pointer to the first value. In case of string or domains, this MUST be the address of pointer.
v2a pointer to the second value. In case of string or domains, this MUST be the address of pointer.
Returns
an integer greater than, equal to, or less than 0 if *v1 is greater than, equal to, or less than *v2.

Definition at line 397 of file val.c.

◆ co_val_read()

size_t co_val_read ( co_unsigned16_t  type,
void *  val,
const uint_least8_t *  begin,
const uint_least8_t *  end 
)

Reads a value of the specified data type from a memory buffer.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address at which to store the value. On success, if val is not NULL, *val contains the read value. On error, *val is left untouched. In the case of strings or domains, val MUST be the address of pointer. Note that this value is not finalized before the read value is stored.
begina pointer to the start of the buffer.
enda pointer to the end of the buffer. For strings and domains, all bytes between begin and end are considered to be part of the value.
Returns
the number of bytes read, or 0 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_write()

Definition at line 481 of file val.c.

◆ co_val_read_sdo()

co_unsigned32_t co_val_read_sdo ( co_unsigned16_t  type,
void *  val,
const void *  ptr,
size_t  n 
)

Reads a value of the specified data type from an SDO buffer.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address at which to store the value. On success, if val is not NULL, *val contains the read value. On error, *val is left untouched. In the case of strings or domains, val MUST be the address of pointer. Note that this value is not finalized before the read value is stored.
ptra pointer to the bytes in the SDO.
nthe number of bytes at ptr.
Returns
0 on success, or an SDO abort code on error.
See also
co_val_read()

Definition at line 700 of file val.c.

◆ co_val_write()

size_t co_val_write ( co_unsigned16_t  type,
const void *  val,
uint_least8_t *  begin,
uint_least8_t *  end 
)

Writes a value of the specified data type to a memory buffer.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be written. In case of string or domains, this MUST be the address of pointer.
begina pointer to the start of the buffer. If begin is NULL, nothing is written.
enda pointer to the end of the buffer. If end is not NULL, and the buffer is too small (i.e., end - begin is less than the return value), nothing is written.
Returns
the number of bytes that would have been written had the buffer been sufficiently large, or 0 on error. In the latter case, the error number can be obtained with get_errc().
See also
co_val_read()

Definition at line 720 of file val.c.

◆ co_val_lex()

size_t co_val_lex ( co_unsigned16_t  type,
void *  val,
const char *  begin,
const char *  end,
struct floc at 
)

Lexes a value of the specified data type from a memory buffer.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address at which to store the value. On success, if val is not NULL, *val contains the lexed value. On error, *val is left untouched. In the case of strings or domains, val MUST be the address of pointer. Note that this value is not finalized before the parsed value is stored.
begina pointer to the start of the buffer.
enda pointer to the end of the buffer (can be NULL if the buffer is null-terminated).
atan optional pointer to the file location of begin (used for diagnostic purposes). On success, if at != NULL, *at points to one past the last character lexed. On error, *at is left untouched.
Returns
the number of characters read.

Definition at line 871 of file val.c.

◆ co_val_print()

size_t co_val_print ( co_unsigned16_t  type,
const void *  val,
char **  pbegin,
char *  end 
)

Prints a value of the specified data type to a memory buffer.

Parameters
typethe data type (in the range [1..27]). This MUST be the object index of one of the static data types.
valthe address of the value to be written. In case of string or domains, this MUST be the address of pointer.
pbeginthe address of a pointer to the start of the buffer. If pbegin or *pbegin is NULL, nothing is written; Otherwise, on exit, *pbegin points to one past the last character written.
enda pointer to the end of the buffer. If end is not NULL, at most end - *pbegin characters are written, and the output may be truncated.
Returns
the number of characters that would have been written had the buffer been sufficiently large.

Definition at line 1263 of file val.c.