diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h index 5bd1ad393..801a771ed 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/action_type_support_struct.h @@ -27,6 +27,10 @@ extern "C" typedef struct rosidl_action_type_support_t rosidl_action_type_support_t; +/// Contains rosidl action type support data. +/* + * Actions are built based on services(goal, result and cancel) and message (feedback and status). + */ struct rosidl_action_type_support_t { const rosidl_service_type_support_t * goal_service_type_support; @@ -36,6 +40,12 @@ struct rosidl_action_type_support_t const rosidl_message_type_support_t * status_message_type_support; }; +/// Get the action type support given a provided action and package. +/* + * \param PkgName name of the package that contains the action + * \param Name action name + * \return a rosidl_action_type_support_t struct if found, otherwise NULL. + */ #define ROSIDL_GET_ACTION_TYPE_SUPPORT(PkgName, Name) \ ROSIDL_TYPESUPPORT_INTERFACE__ACTION_SYMBOL_NAME( \ rosidl_typesupport_c, PkgName, action, Name)() diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h index da000672e..c587e673b 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/message_type_support_struct.h @@ -28,21 +28,51 @@ typedef struct rosidl_message_type_support_t rosidl_message_type_support_t; typedef const rosidl_message_type_support_t * (* rosidl_message_typesupport_handle_function)( const rosidl_message_type_support_t *, const char *); +/// Contains rosidl message type support data struct rosidl_message_type_support_t { + /// String identifier for the type_support. const char * typesupport_identifier; + /// Pointer to the message type support library const void * data; + /// Pointer to the message type support handler function rosidl_message_typesupport_handle_function func; }; +/// Get the message type support handle specific to this identifier. +/** + * The handle's message typesupport identifier function is returned or if the parameters are NULL + * then an assert will happen. + * + * \param handle Handle to message type support + * \param identifier The typesupport identifier to get the handle function for + * \return The associated message typesupport handle function. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_message_type_support_t * get_message_typesupport_handle( const rosidl_message_type_support_t * handle, const char * identifier); +// Get the message type support handle function specific to this identifier. +/** + * If the identifier is the same as this handle's typesupport_identifier the handle is simply + * returned or if the parameters are NULL then an assert will happen. + * + * \param handle Handle to message type support + * \param identifier The typesupport identifier to get the handle function for + * \return if the identifier match's the handle's identifier then the handle's function + * is returned. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_message_type_support_t * get_message_typesupport_handle_function( const rosidl_message_type_support_t * handle, const char * identifier); +/// Get the message type support given a provided action and package. +/* + * \param PkgName Name of the package that contains the message + * \param MsgSubfolder name of the subfolder (for example: msg) + * \param MsgName message name + * \return a rosidl_message_type_support_t struct if founded, otherwise NULL. + */ #define ROSIDL_GET_MSG_TYPE_SUPPORT(PkgName, MsgSubfolder, MsgName) \ ROSIDL_TYPESUPPORT_INTERFACE__MESSAGE_SYMBOL_NAME( \ rosidl_typesupport_c, PkgName, MsgSubfolder, MsgName)() diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h b/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h index ee9d45c7a..bce6ab5d7 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/sequence_bound.h @@ -30,19 +30,47 @@ typedef const rosidl_runtime_c__Sequence__bound * (* rosidl_runtime_c__bound_han struct rosidl_runtime_c__Sequence__bound { + /// String identifier for the type_support. const char * typesupport_identifier; + /// Pointer to type support handle function const void * data; rosidl_runtime_c__bound_handle_function func; }; +/// Get the message bounds handle specific to this identifier. +/** + * The handle's sequence bound is simply returned or if the parameters are NULL then an assert + * will happen. + * + * \param handle Handle to service type support + * \param identifier The identifier to get the handle for + * \return The associated sequence bound handle function. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_runtime_c__Sequence__bound * get_sequence_bound_handle( const rosidl_runtime_c__Sequence__bound * handle, const char * identifier); +/// Get the message bounds handle function specific to this identifier. +/** + * If the identifier is the same as this handle function's identifier the handle is simply returned + * or if the parameters are NULL then an assert will happen. + * + * \param handle Handle to service type support + * \param identifier The identifier to get the handle function for + * \return if the identifier match's the handle's identifier then the handle's function + * is returned. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_runtime_c__Sequence__bound * get_sequence_bound_handle_function( const rosidl_runtime_c__Sequence__bound * handle, const char * identifier); +/// Get the sequence bounds given a provided action and package. +/* + * \param PkgName Name of the package that contains the message + * \param MsgSubfolder name of the subfolder (foe example: msg) + * \param MsgName message name + * \return a rosidl_message_bounds_t struct if founded, otherwise NULL. + */ #define ROSIDL_GET_SEQUENCE_BOUNDS(PkgName, MsgSubfolder, MsgName) \ ROSIDL_BOUNDS_INTERFACE__MESSAGE_SYMBOL_NAME( \ rosidl_typesupport_c, PkgName, MsgSubfolder, MsgName)() diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h b/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h index d240c3828..368c94f03 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/service_type_support_struct.h @@ -29,21 +29,51 @@ typedef struct rosidl_service_type_support_t rosidl_service_type_support_t; typedef const rosidl_service_type_support_t * (* rosidl_service_typesupport_handle_function)( const rosidl_service_type_support_t *, const char *); +/// Contains rosidl service type support data struct rosidl_service_type_support_t { + /// String identifier for the type_support. const char * typesupport_identifier; + /// Pointer to the service type support library const void * data; + /// Pointer to the service type support handler function rosidl_service_typesupport_handle_function func; }; +/// Get the service type support handle specific to this identifier. +/** + * The handle's message typesupport identifier function is returned or if the parameters are NULL + * then an assert will happen. + * + * \param handle Handle to service type support + * \param identifier The typesupport identifier to get the handle function for + * \return The associated service typesupport handle function. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_service_type_support_t * get_service_typesupport_handle( const rosidl_service_type_support_t * handle, const char * identifier); +/// Get the service type support handle function specific to this identifier. +/** +* If the identifier is the same as this handle's typesupport_identifier the handle is simply +* returned or if the parameters are NULL then an assert will happen. + * + * \param handle Handle to service type support + * \param identifier The typesupport identifier to get the handle function for + * \return if the identifier match's the handle's identifier then the handle's function + * is returned. + */ ROSIDL_GENERATOR_C_PUBLIC const rosidl_service_type_support_t * get_service_typesupport_handle_function( const rosidl_service_type_support_t * handle, const char * identifier); +/// Get the service type support given a provided action and package. +/* + * \param PkgName Name of the package that contains the service + * \param SrvSubfolder name of the subfolder (for example: srv) + * \param SrvName service name + * \return a rosidl_service_type_support_t struct if founded, otherwise NULL. + */ #define ROSIDL_GET_SRV_TYPE_SUPPORT(PkgName, SrvSubfolder, SrvName) \ ROSIDL_TYPESUPPORT_INTERFACE__SERVICE_SYMBOL_NAME( \ rosidl_typesupport_c, PkgName, SrvSubfolder, SrvName)() diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h b/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h index f2a7db0e5..72a0066ce 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/string_functions.h @@ -26,44 +26,117 @@ extern "C" #endif /// Initialize a rosidl_runtime_c__String structure. -/* The contents of rosidl_runtime_c__String are initialized to a single null character ('\0'). +/* + * The contents of rosidl_runtime_c__String are initialized to a single null character ('\0'). * The string initially has size 0 and capacity 1. * Size represents the size of the contents of the string, while capacity represents the overall * storage of the string (counting the null terminator). * All strings must be null-terminated. + * The rosidl_runtime_c__String structure should be deallocated using the given function + * rosidl_runtime_c__String__fini() when it is no longer needed. + * Calling this function with an already initialized U16 string sequence structure will leak + * memory. + * + * \param[inout] str a pointer to a rosidl_runtime_c__String structure + * \return true if successful, false if the passed string pointer is null + * or the memory allocation failed */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__String__init(rosidl_runtime_c__String * str); +/// Deallocate the memory of the rosidl_runtime_c__String structure. +/* +* Calling the function with an already deallocated sequence is a no-op. +* +* \param[inout] str a pointer to a rosidl_runtime_c__String structure to be finalized +*/ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__String__fini(rosidl_runtime_c__String * str); +/// Assign the c string pointer of n characters to the rosidl_runtime_c__String structure. +/* + * \param[inout] str a pointer to a string structure + * \param[in] value c string pointer to be assigned + * \param[in] n size of the value string + * \return true if successful, false if the passed string pointer is null + * or if the passed value pointer is null or if the size is higher than SIZE_MAX + * or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__String__assignn( rosidl_runtime_c__String * str, const char * value, size_t n); +/// Assign the c string pointer to the rosidl_runtime_c__String structure. +/* + * + * This function is identical to rosidl_runtime_c__String__assignn() except the length of the + * c string does not have to be given and therefore the c string must be null terminated. + * + * \see rosidl_runtime_c__String__assignn() + * + * \param[inout] str a pointer to a rosidl_runtime_c__String structure + * \param[in] value c string pointer to be assigned + * \return true if successful, false if the passed string pointer is null + * or if the passed value pointer is null or if the size is higher than SIZE_MAX + * or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__String__assign( rosidl_runtime_c__String * str, const char * value); +/// Initialize a rosidl_runtime_c__String__Sequence__init structure. +/* + * The rosidl_runtime_c__String__Sequence is initialized with the size passed to the function. + * The rosidl_runtime_c__String__Sequence structure should be deallocated using the given function + * rosidl_runtime_c__String__Sequence__fini() when it is no longer needed. + * Calling this function with an already initialized U16 string sequence structure will leak + * memory. + * + * \param[inout] sequence a pointer to a string sequence + * \param[in] size represents the size of the string sequence + * \return true if successful, false if the passed string pointer is null + * or the memory allocation failed + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__String__Sequence__init( rosidl_runtime_c__String__Sequence * sequence, size_t size); +/// Deallocate the memory of the string sequence structure. +/* + * Calling the function with an already deallocated sequence is a no-op. + * + * \param[inout] sequence a pointer to a string sequence to be finalized + */ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__String__Sequence__fini( rosidl_runtime_c__String__Sequence * sequence); +/// Create a rosidl_runtime_c__String__Sequence structure with a specific size. +/* + * The string sequence initially has size and capacity equal to the size argument passed to the + * function. + * The rosidl_runtime_c__String__Sequence structure should be deallocated using the given function + * rosidl_runtime_c__String__Sequence__destroy() when it is no longer needed. + * + * \param[in] size of the desired string sequence + * \return a string sequence if initialization was successfully, otherwise NULL. + */ ROSIDL_GENERATOR_C_PUBLIC rosidl_runtime_c__String__Sequence * rosidl_runtime_c__String__Sequence__create(size_t size); +/// Destroy a rosidl_runtime_c__String__Sequence structure. +/* + * Calling the function with an already deallocated sequence is a no-op. + * + * \param[inout] sequence a pointer to a string sequence to be finalized + */ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__String__Sequence__destroy( diff --git a/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h b/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h index eddf29a73..4207fc47a 100644 --- a/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h +++ b/rosidl_runtime_c/include/rosidl_runtime_c/u16string_functions.h @@ -31,53 +31,159 @@ extern "C" * Size represents the size of the contents of the string, while capacity represents the overall * storage of the string (counting the null terminator). * All strings must be null-terminated. + * The rosidl_runtime_c__U16String structure should be deallocated using the given function + * rosidl_runtime_c__U16String__fini() when it is no longer needed. + * Calling this function with an already initialized U16 string sequence structure will leak + * memory. + * + * \param[inout] str a pointer to a U16 string structure + * \return true if successful, false if the passed string pointer is null + * or the memory allocation failed */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__init(rosidl_runtime_c__U16String * str); +/// Deallocate the memory of the rosidl_runtime_c__U16String structure. +/* +* Calling the function with an already deallocated sequence is a no-op. +* +* \param[inout] str a pointer to a U16 string structure to be finalized +*/ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__U16String__fini(rosidl_runtime_c__U16String * str); +/// Assign the uint16_t value of n characters to the rosidl_runtime_c__U16String structure. +/* + * This function returns `false` if memory cannot be allocated, + * if the input uint16_t pointer is null or if the size is higher than SIZE_MAX. + * In both cases no error message is set. + * + * \param[inout] str a pointer to a U16 string structure + * \param[in] value points to a sequence of 16 bit chars + * \param[in] n size of the value string + * \return true if successful, false if the passed string pointer is null + * or if the passed value pointer is null or if the size is higher than SIZE_MAX + * or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__assignn( rosidl_runtime_c__U16String * str, const uint16_t * value, size_t n); +/// Assign the c string pointer value of n characters to the rosidl_runtime_c__U16String structure. +/* + * This function is identical to rosidl_runtime_c__U16String__assignn() except the type of the + * value is c string pointer + * + * \see rosidl_runtime_c__U16String__assignn() + * + * \param[inout] str a pointer to a U16 string structure + * \param[in] value points to a sequence of 16 bit chars + * \param[in] n size of the value string + * \return true if successful, false if the passed string pointer is null + * or if the passed value pointer is null or if the size is higher than SIZE_MAX + * or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__assignn_from_char( rosidl_runtime_c__U16String * str, const char * value, size_t n); +/// Assign the uint16_t pointer to the rosidl_runtime_c__U16String structure. +/* + * This function is identical to rosidl_runtime_c__U16String__assignn() except the length of the + * uint16_t does not have to be given. + * rosidl_runtime_c__U16String__len() is being used to determine the length of the passed string. + * + * \see rosidl_runtime_c__U16String__assignn() + * + * \param[inout] str a pointer to a rosidl_runtime_c__U16String structure + * \param[in] value points to a sequence of 16 bit chars + * \return true if successful, false if the passed string pointer is null + * or if the passed value pointer is null or if the size is higher than SIZE_MAX + * or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__assign( rosidl_runtime_c__U16String * str, const uint16_t * value); +/// Get the length of the uint16_t pointer. +/* + * This function returns the length of the input value pointer. + * + * \param[in] value points to a sequence of 16 bit chars for which the first null char is + * determined + * \return the size of the input value pointer or zero if the pointer is NULL + */ ROSIDL_GENERATOR_C_PUBLIC size_t rosidl_runtime_c__U16String__len(const uint16_t * value); +/// Resize the uint16_t pointer. +/* + * This function resize the input value pointer. + * + * \param[in] n the new size of the internal buffer + * \return true if successful, false if the passed string pointer is null + * or if the size is higher than SIZE_MAX or if the memory reallocation failed. + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__resize( rosidl_runtime_c__U16String * str, size_t n); +/// Initialize a U16 string sequence structure. +/* + * The rosidl_runtime_c__U16String__Sequence is initialized to the size passed to the function. + * The U16 string sequence structure should be deallocated using the given + * function rosidl_runtime_c__U16String__Sequence__fini() when it is no longer needed. + * Calling this function with an already initialized U16 string sequence structure will leak + * memory. + * + * \param[inout] sequence a pointer to a U16 string sequence structure + * \param[in] size represents the size of the U16 string + * \return true if successful, false if the passed string pointer is null + * or the memory allocation failed + */ ROSIDL_GENERATOR_C_PUBLIC bool rosidl_runtime_c__U16String__Sequence__init( rosidl_runtime_c__U16String__Sequence * sequence, size_t size); +/// Deallocate the memory of the string sequence structure. +/* + * Calling the function with an already deallocated sequence is a no-op. + * + * \param[inout] sequence a pointer to a U16 string to be finalized + */ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__U16String__Sequence__fini( rosidl_runtime_c__U16String__Sequence * sequence); +/// Create a U16 string sequence structure with a specific size. +/* + * The U16 string sequence initially has size and capacity equal to the size + * argument. + * The U16 string sequence structure should be deallocated using the given + * function rosidl_runtime_c__U16String__Sequence__destroy() when it is no longer needed. + * + * \param[in] size of the desired U16 string + * \return a U16 string sequence if initialization was successfully, otherwise NULL. + */ ROSIDL_GENERATOR_C_PUBLIC rosidl_runtime_c__U16String__Sequence * rosidl_runtime_c__U16String__Sequence__create(size_t size); +/// Destroy a U16 string sequence structure. +/* + * Calling the function with an already deallocated sequence is a no-op. + * + * \param[inout] sequence a pointer to a U16 string sequence to be finalized + */ ROSIDL_GENERATOR_C_PUBLIC void rosidl_runtime_c__U16String__Sequence__destroy(