Describe the structure of marshallable types. More...

Data Structures

struct  LWMsgTypeClass
 Custom type class. More...
 

Macros

#define LWMSG_HANDLE(htype)
 Define a handle. More...
 
#define LWMSG_MEMBER_HANDLE(type, field, htype)
 Define a handle as a member. More...
 
#define LWMSG_ATTR_HANDLE_LOCAL_FOR_RECEIVER
 Ensure that handle is local to receiving peer. More...
 
#define LWMSG_ATTR_HANDLE_LOCAL_FOR_SENDER
 Ensure that handle is local to sending peer. More...
 
#define LWMSG_VOID
 Specify an empty type. More...
 
#define LWMSG_MEMBER_VOID(type, field)
 Specify an empty member. More...
 
#define LWMSG_TYPESPEC(spec)
 Reference another type specification. More...
 
#define LWMSG_MEMBER_TYPESPEC(type, field, spec)
 Reference another type specification as a member. More...
 
#define LWMSG_TYPE_END
 End a type specification. More...
 
#define LWMSG_STRUCT_END
 End a structure specification. More...
 
#define LWMSG_UNION_END
 End a union specification. More...
 
#define LWMSG_POINTER_END
 End a pointer specification. More...
 
#define LWMSG_ARRAY_END
 End an array specification. More...
 
#define LWMSG_STRUCT_BEGIN(type)
 Begin a structure definition. More...
 
#define LWMSG_MEMBER_STRUCT_BEGIN(type, field)
 Begin a structure definition as a member. More...
 
#define LWMSG_UNION_BEGIN(type)
 Begin a union definition. More...
 
#define LWMSG_MEMBER_UNION_BEGIN(type, field)
 Begin a union definition as a member. More...
 
#define LWMSG_MEMBER_INTEGER(type, field, width, sign)
 Define an integer member. More...
 
#define LWMSG_INTEGER(type, width, sign)
 Define an integer. More...
 
#define LWMSG_ATTR_LENGTH_STATIC(count)
 Indicate static length. More...
 
#define LWMSG_ATTR_LENGTH_MEMBER(type, field)
 Indicate correlated length member. More...
 
#define LWMSG_ATTR_ZERO_TERMINATED
 Indicate null termination. More...
 
#define LWMSG_ATTR_ENCODING(enc)
 Indicate data encoding. More...
 
#define LWMSG_ATTR_SENSITIVE
 Indicate sensitive information. More...
 
#define LWMSG_ATTR_ALIASABLE
 Indicate aliasable pointer. More...
 
#define LWMSG_ATTR_STRING
 Indicate C string. More...
 
#define LWMSG_ATTR_MAX_ALLOC(max)
 Limit memory allocation for pointer referent. More...
 
#define LWMSG_ATTR_TAG(value)
 Indicate union tag. More...
 
#define LWMSG_ATTR_DISCRIM(type, field)
 Indicate correlated union discriminator. More...
 
#define LWMSG_ATTR_VERIFY(func, data)
 Apply custom data verifier. More...
 
#define LWMSG_ATTR_RANGE(low, high)
 Constrain range of integer type. More...
 
#define LWMSG_ATTR_NOT_NULL
 Restrict pointer nullability. More...
 
#define LWMSG_MEMBER_POINTER_BEGIN(type, field)
 Define a pointer as a member. More...
 
#define LWMSG_POINTER_BEGIN
 Define a pointer. More...
 
#define LWMSG_MEMBER_ARRAY_BEGIN(type, field)
 Define an array as a member. More...
 
#define LWMSG_CUSTOM(type, tclass, tdata)
 Define a custom type. More...
 
#define LWMSG_MEMBER_CUSTOM(type, field, tclass, tdata)
 Define a custom type as a member. More...
 
#define LWMSG_ATTR_CUSTOM(value)
 Apply custom type attribute. More...
 
#define LWMSG_ENUM_BEGIN(type, width, sign)
 Begin enum definition. More...
 
#define LWMSG_ENUM_END
 End enum definition. More...
 
#define LWMSG_ENUM_VALUE(value)
 Define enum scalar value. More...
 
#define LWMSG_ENUM_NAMED_VALUE(name, value)
 Define enum scalar value with explicit name. More...
 
#define LWMSG_ENUM_MASK(value)
 Define enum mask value. More...
 
#define LWMSG_ENUM_NAMED_MASK(name, value)
 Define enum mask value with explicit name. More...
 
#define LWMSG_MEMBER_INT8(type, field)
 Define a signed 8-bit integer member. More...
 
#define LWMSG_MEMBER_INT16(type, field)
 Define a signed 16-bit integer member. More...
 
#define LWMSG_MEMBER_INT32(type, field)
 Define a signed 32-bit integer member. More...
 
#define LWMSG_MEMBER_INT64(type, field)
 Define a signed 64-bit integer member. More...
 
#define LWMSG_MEMBER_UINT8(type, field)
 Define an unsigned 8-bit integer member. More...
 
#define LWMSG_MEMBER_UINT16(type, field)
 Define an unsigned 16-bit integer member. More...
 
#define LWMSG_MEMBER_UINT32(type, field)
 Define an unsigned 32-bit integer member. More...
 
#define LWMSG_MEMBER_UINT64(type, field)
 Define an unsigned 64-bit integer member. More...
 
#define LWMSG_INT8(type)
 Define a signed 8-bit integer. More...
 
#define LWMSG_INT16(type)
 Define a signed 16-bit integer. More...
 
#define LWMSG_INT32(type)
 Define a signed 32-bit integer. More...
 
#define LWMSG_INT64(type)
 Define a signed 64-bit integer. More...
 
#define LWMSG_UINT8(type)
 Define an unsigned 8-bit integer. More...
 
#define LWMSG_UINT16(type)
 Define an unsigned 16-bit integer. More...
 
#define LWMSG_UINT32(type)
 Define an unsigned 32-bit integer. More...
 
#define LWMSG_UINT64(type)
 Define an unsigned 64-bit integer. More...
 
#define LWMSG_MEMBER_PSTR(type, field)
 Define a member pointer to a string. More...
 
#define LWMSG_PSTR
 Define a pointer to a string. More...
 
#define LWMSG_STRUCT(type,...)
 Define a structure (compact) More...
 
#define LWMSG_POINTER(...)
 Define a pointer (compact) More...
 
#define LWMSG_UNION(type,...)
 Define a union (compact) More...
 
#define LWMSG_MEMBER_STRUCT(type, field,...)
 Define a structure as a member (compact) More...
 
#define LWMSG_MEMBER_POINTER(type, field,...)
 Define a pointer as a member (compact) More...
 
#define LWMSG_MEMBER_UNION(type, field,...)
 Define a union as a member (compact) More...
 
#define LWMSG_MEMBER_ARRAY(type, field,...)
 Define an array as a member (compact) More...
 

Typedefs

typedef struct LWMsgType LWMsgType
 Type. More...
 
typedef LWMsgStatus(* LWMsgTypeMarshalFunction )(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *transmit_object, void *data)
 Custom marshal function. More...
 
typedef LWMsgStatus(* LWMsgTypeUnmarshalFunction )(struct LWMsgDataContext *context, LWMsgType *type, void *transmit_object, void *object, void *data)
 Custom unmarshal function. More...
 
typedef void(* LWMsgTypeDestroyPresentedFunction )(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *data)
 Destroy presented object function. More...
 
typedef void(* LWMsgTypeDestroyTransmittedFunction )(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *data)
 Destroy transmitted object function. More...
 
typedef LWMsgStatus(* LWMsgTypePrintFunction )(struct LWMsgDataContext *context, LWMsgType *attr, void *object, void *data, LWMsgBuffer *buffer)
 Custom print function. More...
 
typedef size_t const LWMsgTypeSpec
 Marshaller type specification. More...
 
typedef LWMsgStatus(* LWMsgVerifyFunction )(struct LWMsgDataContext *context, LWMsgBool unmarshalling, void *object, void *data)
 Custom data verification function. More...
 

Enumerations

enum  LWMsgSignage {
  LWMSG_SIGNED,
  LWMSG_UNSIGNED
}
 Indicate signed or unsigned status. More...
 
enum  LWMsgTypeFlags {
  LWMSG_TYPE_FLAG_NOT_NULL,
  LWMSG_TYPE_FLAG_SENSITIVE,
  LWMSG_TYPE_FLAG_PROMOTED,
  LWMSG_TYPE_FLAG_RANGE,
  LWMSG_TYPE_FLAG_ALIASABLE
}
 Type flag bitmask. More...
 

Functions

LWMsgTypeFlags lwmsg_type_get_flags (const LWMsgType *type)
 Get type flags. More...
 
size_t lwmsg_type_get_custom_flags (const LWMsgType *type)
 Get custom type flags. More...
 
LWMsgStatus lwmsg_type_get_integer_range (const LWMsgType *type, size_t *low, size_t *high)
 Get integer range constraint. More...
 

Detailed Description

This module provides the means to describe the layout of C types such that they can be processed by the LWMsg marshaller. A type specification consists of a global, statically-initialized array of the LWMsgTypeSpec type. The initializer should consist of a set of braces enclosing a comma-separated list of type specification macros.

In order to allow for automated marshalling, a type specification must include additional information which is not explicit in the C type definition, such as how to determine the dynamic length of arrays and pointer referents. Consider the following example of a simple C structure and its LWMsg specification.

* typedef struct _Foo
* {
* char* name;
* size_t length;
* long* numbers;
* } Foo;
*
* LWMsgTypeSpec foo_spec[] =
* {
* // Begin layout of "Foo" structure
* // Foo has a member "name" which is a pointer to a null-terminated string
* LWMSG_MEMBER_PSTR(Foo, name),
* // Foo has a member "length" which should be marshalled as an unsigned 32-bit integer
* LWMSG_MEMBER_UINT32(Foo, length),
* // Foo has a member "numbers" which is a pointer
* // The pointer points to one or more longs which are marshalled as signed 64-bit integers
* LWMSG_INT64(long),
* // End the member "numbers" pointer
* // Indicate that the dynamic length of "numbers" is the value of "length"
* LWMSG_ATTR_LENGTH_MEMBER(Foo, length),
* // End the "Foo" structure
* // End the type specification
* };
*

Type specifications have the following restrictions compared to C type definitions:

Type specifications have the following leniencies compared to C type definitions:

Macro Definition Documentation

#define LWMSG_HANDLE (   htype)

Defines a handle type within a type specification. Handles are opaque pointer types which are only usable with associations.

Parameters
htypethe name of the handle type
#define LWMSG_MEMBER_HANDLE (   type,
  field,
  htype 
)

Defines a handle type as a member of a struct or union. Handles are opaque pointer types which are only usable with associations.

Parameters
typethe type of the containing struct or union
fieldthe field within the containing type
htypethe name of the handle type
#define LWMSG_ATTR_HANDLE_LOCAL_FOR_RECEIVER

Specifies that the previous type or member, which must be a handle, must be a local handle from the perspective of the receiver.

#define LWMSG_ATTR_HANDLE_LOCAL_FOR_SENDER

Specifies that the previous type or member, which must be a handle, must be a local handle from the perspective of the sender.

#define LWMSG_VOID

Specifies an empty (zero-length) type.

#define LWMSG_MEMBER_VOID (   type,
  field 
)

Specifies an empty (zero-length) member. This is primarily useful for indicating empty arms of a union. The field name can be arbitrary.

Parameters
typethe name of the containing type
fieldthe name of the member
#define LWMSG_TYPESPEC (   spec)

References another type specification, treating it as though it were inserted in place into the type specification currently being defined. This mechanism may be used to avoid repeating definitions for common types.

Parameters
specthe LWMsgTypeSpec[] to reference
#define LWMSG_MEMBER_TYPESPEC (   type,
  field,
  spec 
)

Defines a member of a structure or union by referencing a separate type specification. This mechanism may be used to avoid repeating definitions for common types.

Parameters
typethe name of the containing type
fieldthe name of the member
specthe LWMsgTypeSpec[] which specifies the member type
#define LWMSG_TYPE_END

Marks the end of a type specification. All type specifications must be terminated with this macro.

#define LWMSG_STRUCT_END

Marks the end of a structure specification started with LWMSG_STRUCT_BEGIN() or LWMSG_MEMBER_STRUCT_BEGIN().

#define LWMSG_UNION_END

Marks the end of a union specification started with LWMSG_UNION_BEGIN() or LWMSG_MEMBER_UNION_BEGIN().

#define LWMSG_POINTER_END

Marks the end of a pointer specification started with LWMSG_POINTER_BEGIN() or LWMSG_MEMBER_POINTER_BEGIN().

#define LWMSG_ARRAY_END

Marks the end of an array specification started with LWMSG_MEMBER_ARRAY_BEGIN().

#define LWMSG_STRUCT_BEGIN (   type)

Begins the definition of a structure within a type specification. The end of the definition must be marked with LWMSG_STRUCT_END

Parameters
typethe name of the structure type
#define LWMSG_MEMBER_STRUCT_BEGIN (   type,
  field 
)

Begins the definition of a structure which is an inline member of the structure or union currently being defined. The end of the definition must be marked with LWMSG_STRUCT_END.

Parameters
typethe name of the containing structure or union type
fieldthe name of the member
#define LWMSG_UNION_BEGIN (   type)

Begins the definition of a union within a type specification. The end of the definition must be marked with LWMSG_UNION_END

Parameters
typethe name of the union type
#define LWMSG_MEMBER_UNION_BEGIN (   type,
  field 
)

Begins the definition of a union which is an inline member of the structure or union currently being defined. The end of the definition must be marked with LWMSG_UNION_END.

Parameters
typethe name of the containing structure or union type
fieldthe name of the member
#define LWMSG_MEMBER_INTEGER (   type,
  field,
  width,
  sign 
)

Defines an integer member of a struct or union.

Parameters
typethe name of the containing structure or union type
fieldthe name of the member
widththe marshalled size of the integer in bytes
signthe signedness of the integer as a LWMsgSignage
#define LWMSG_INTEGER (   type,
  width,
  sign 
)

Defines an integer

Parameters
typethe unmarshalled, C type of the integer
widththe marshalled size of the integer in bytes
signthe signedness of the integer as a LWMsgSignage
#define LWMSG_ATTR_LENGTH_STATIC (   count)

Indicates the static length of the immediately previous array or pointer type in a type specification

Parameters
countthe number of elements in the previous type
#define LWMSG_ATTR_LENGTH_MEMBER (   type,
  field 
)

Indicates that that length of the immediately previous array or pointer member is equal to the value of the specified integer member, which must be defined before the pointer or array member.

Parameters
typethe type of the containing structure
fieldthe name of the field which contains the length
#define LWMSG_ATTR_ZERO_TERMINATED

Indicates that the immediately previous array or pointer member has a length determined by null- or zero- termination.

#define LWMSG_ATTR_ENCODING (   enc)

Indicates that the immediately previous array or pointer represents data in the specified encoding. This is used as a hint by functions such as lwmsg_data_print_graph_alloc() to show the data in a human-readable form, but has no effect on how the data is marshalled. The encoding is specified as an all-uppercase string which should be a valid encoding name recognized by the system iconv_open() function. Alternatively, it can be one of the following special lowercase strings recognized by lwmsg:

  • "ucs-2": specifies UCS-2 encoding with native endianness. The iconv-recognized "UCS-2" encoding name is inconsistent across different implementations – on some platforms it indicates native endianness, while on others it is always big or little regardless of CPU architecture. Use this alias instead for consistent cross-platform behavior.
  • "hex+ascii": indicates that the data should be displayed in side-by-side hexadecimal and ASCII form, like the hexdump -C command available on many UNIX systems. Each 16-byte block is shown on its own line with its 32-bit offset in hex, the hex value of each byte, and the ASCII interpretation of each byte if it is a valid ASCII codepoint and not a control character, or '.' otherwise.
Parameters
enca string specifying the encoding
#define LWMSG_ATTR_SENSITIVE

Indicates that the immediately previous type or member contains sensitive information (e.g. a password) and should not be displayed when printed.

#define LWMSG_ATTR_ALIASABLE

Indicates that the immediately previous type or member, which must be a pointer or pointer-like type, is aliasable – that is, multiple instances of the same pointer may appear in the data object graph.

#define LWMSG_ATTR_STRING

Indicates that the immediately previous array or pointer represents a plain C string. That is, it is nul-terminated and encoded in the program's current locale.

#define LWMSG_ATTR_MAX_ALLOC (   max)

Indicates that the marshaller should refuse to allocate more than the given number of bytes when unmarshalling the referent of the immediately previous pointer type. An attempt to exceed this value will result in an LWMSG_STATUS_OVERFLOW error.

Parameters
maxthe maximum number of bytes to allocate
#define LWMSG_ATTR_TAG (   value)

Indicates that the immediately previous member of a union is associated with a particular integer tag. All members of a union must be marked with this attribute.

Parameters
valuethe integer value associated with the member
#define LWMSG_ATTR_DISCRIM (   type,
  field 
)

Indicates that the immediately previous member, which must be a union type, has an active arm which is determined by the tag stored in the specified discriminator member. All uses of unions must be marked with this attribute.

Parameters
typethe name of the containing structure
fieldthe name of the member which holds the tag value
#define LWMSG_ATTR_VERIFY (   func,
  data 
)

Applies a custom data verification function to the previous type or member. The function will be called with the in-memory form of the data immediately before it is marshalled or immediately after it is unmarshalled.

Only one custom data verifier may be applied to a given type or member.

Parameters
functhe verifier function
dataa constant user data pointer to pass to the function
#define LWMSG_ATTR_RANGE (   low,
  high 
)

Constrains the range of an integer type to the specified bounds. Attempts to marshal or unmarshal data where the type exceeds these bounds will result in an immediate error.

Parameters
lowthe lower bound of the range (inclusive)
highthe upper bound of the range (inclusive)
#define LWMSG_ATTR_NOT_NULL

Specifies that the previous type or member, which must be a pointer, must not be NULL. Attempts to marshal or unmarshal data where the affected type or member is NULL will result in an immediate error.

#define LWMSG_MEMBER_POINTER_BEGIN (   type,
  field 
)

Defines a pointer which is a member of the current structure or union. This must be followed by the definition of the pointer's contents. The end of the pointer definition must be marked by LWMSG_POINTER_END.

Parameters
typethe name of the containing structure
fieldthe name of the pointer member
#define LWMSG_POINTER_BEGIN

Defines a pointer. This must be followed by the definition of the pointer's contents. The end of the pointer definition must be marked by LWMSG_POINTER_END.

#define LWMSG_MEMBER_ARRAY_BEGIN (   type,
  field 
)

Defines an array which is a member of the current structure or union. This must be followed by the definition of the array's contents. The end of the array definition must be marked by LWMSG_ARRAY_END.

An array, as opposed to a pointer, has contents which are stored inline in the the containing structure or union. That is, each element of the array is stored as if it were itself a member. This difference corresponds naturally to the difference between * and [] types in C structures.

Parameters
typethe name of the containing structure
fieldthe name of the array member
#define LWMSG_CUSTOM (   type,
  tclass,
  tdata 
)

Defines a custom type with user-specified marshaller logic.

Parameters
typethe C type
tclassa constant pointer to the LWMsgCustomTypeClass structure containing marshalling methods
tdataa constant pointer to arbitrary data which will be passed to the marshalling methods
#define LWMSG_MEMBER_CUSTOM (   type,
  field,
  tclass,
  tdata 
)

Defines a custom type with user-specified marshaller logic as a member of a structure or union.

Parameters
typethe name of the containing type
fieldthe name of the member
tclassa constant pointer to the LWMsgCustomTypeClass structure containing marshalling methods
tdataa constant pointer to arbitrary data which will be passed to the marshalling methods
#define LWMSG_ATTR_CUSTOM (   value)

Applies a custom attribute to the previous type or member, which must be a custom type. The bitwise or of all custom attribute values will be made available to the marshal and unmarshal functions for the custom type.

Parameters
valuethe value of the attribute to apply
#define LWMSG_ENUM_BEGIN (   type,
  width,
  sign 
)

Defines an enumerated integer type with the given underlying C type, width, and sign. An enum value can consist of one of a set of scalar values (specified with LWMSG_ENUM_VALUE()) and/or a bitwise-or'd set of mask values (specified with LWMSG_ENUM_MASK())

Parameters
typethe name of the C enum type
widththe width of the enum when marshalled, in bytes
signthe sign of the enum when marshalled, an LWMsgSignage value
#define LWMSG_ENUM_END

Ends an enum definition started by LWMSG_ENUM_BEGIN()

#define LWMSG_ENUM_VALUE (   value)

Defines a possible scalar value of an enum type

Parameters
valuethe value
#define LWMSG_ENUM_NAMED_VALUE (   name,
  value 
)

Defines a possible scalar value of an enum type with an explicit name.

Parameters
namethe name of the constant
valuethe value
#define LWMSG_ENUM_MASK (   value)

Defines a potential bitmask value of an enum type

Parameters
valuethe value
#define LWMSG_ENUM_NAMED_MASK (   name,
  value 
)

Defines a potential bitmask value of an enum type with an explicit name.

Parameters
namethe name of the constant
valuethe value
#define LWMSG_MEMBER_INT8 (   type,
  field 
)

Defines a signed 8-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_INT16 (   type,
  field 
)

Defines a signed 16-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_INT32 (   type,
  field 
)

Defines a signed 32-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_INT64 (   type,
  field 
)

Defines a signed 64-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_UINT8 (   type,
  field 
)

Defines an unsigned 8-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_UINT16 (   type,
  field 
)

Defines an unsigned 16-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_UINT32 (   type,
  field 
)

Defines an unsigned 32-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_MEMBER_UINT64 (   type,
  field 
)

Defines an unsigned 64-bit integer member of a struct or union. This is a convenient shortcut for a full LWMSG_MEMBER_INTEGER() invocation.

Parameters
typethe name of the containing structure or union
fieldthe name of the member
#define LWMSG_INT8 (   type)

Defines a signed 8-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_INT16 (   type)

Defines a signed 16-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_INT32 (   type)

Defines a signed 32-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_INT64 (   type)

Defines a signed 64-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_UINT8 (   type)

Defines an unsigned 8-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_UINT16 (   type)

Defines an unsigned 16-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_UINT32 (   type)

Defines an unsigned 32-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_UINT64 (   type)

Defines an unsigned 64-bit integer type. This is a convenient shortcut for a full LWMSG_INTEGER() invocation.

Parameters
typethe unmarshalled type
#define LWMSG_MEMBER_PSTR (   type,
  field 
)

Defines a pointer to an 8-bit, null-terminated character string as a member of a struct or union. This is a convenient shortcut for marshalling plain C strings, and is equivalent to the following:

Parameters
typethe containing struct or union type
fieldthe member of the struct or union
#define LWMSG_PSTR

Defines a pointer to an 8-bit, null-terminated character string. This is a convenient shortcut for marshalling plain C strings, and is equivalent to the following:

Parameters
typethe containing struct or union type
fieldthe member of the struct or union
#define LWMSG_STRUCT (   type,
  ... 
)

Defines a structure in a more compact fashion. It is equivalent to the following expanded form:

* ... ,
*
Parameters
typethe C structure type
...the contents of the structure specification
#define LWMSG_POINTER (   ...)

Defines a pointer in a more compact fashion. It is equivalent to the following expanded form:

* ... ,
* LWMSG_POINTER_END
*
Parameters
...the contents of the pointer specification
#define LWMSG_UNION (   type,
  ... 
)

Defines a union in a more compact fashion. It is equivalent to the following expanded form:

* ... ,
*
Parameters
typethe C union type
...the contents of the union specification
#define LWMSG_MEMBER_STRUCT (   type,
  field,
  ... 
)

Defines a structure as a member in a more compact fashion. It is equivalent to the following expanded form:

* ... ,
*
Parameters
typethe containing C type
fieldthe member name
...the contents of the structure specification
#define LWMSG_MEMBER_POINTER (   type,
  field,
  ... 
)

Defines a pointer as a member in a more compact fashion. It is equivalent to the following expanded form:

* ... ,
* LWMSG_POINTER_END
*
Parameters
typethe containing C type
fieldthe member name
...the contents of the structure specification
#define LWMSG_MEMBER_UNION (   type,
  field,
  ... 
)

Defines a union as a member in a more compact fashion. It is equivalent to the following expanded form:

* LWMSG_MEMBER_UNION_BEGIN(type, field),
* ... ,
*
Parameters
typethe containing C type
fieldthe member name
...the contents of the union specification
#define LWMSG_MEMBER_ARRAY (   type,
  field,
  ... 
)

Defines an array as a member in a more compact fashion. It is equivalent to the following expanded form:

* LWMSG_MEMBER_ARRAY_BEGIN(type, field),
* ... ,
*
Parameters
typethe containing C type
fieldthe member name
...the contents of the structure specification

Typedef Documentation

typedef struct LWMsgType LWMsgType

An opqaue handle representing a type.

typedef LWMsgStatus(* LWMsgTypeMarshalFunction)(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *transmit_object, void *data)

A callback function which converts a presented type to its transmitted form. The transmitted_object parameter will point to a block of memory large enough for the transmitted type. Any resources allocated to construct the transmitted object can be freed by the corresponding LWMsgTypeDestroyTransmittedFunction.

Parameters
[in]contextthe data context
[in]typethe type to marshal
[in]presented_objectthe presented object
[out]transmitted_objectthe object which will be transmitted
[in]datathe user data pointer specified to LWMSG_CUSTOM() or LWMSG_MEMBER_CUSTOM() in the type specification
Return values
LWMSG_STATUS_SUCCESSsuccess
...implementation-specific error
typedef LWMsgStatus(* LWMsgTypeUnmarshalFunction)(struct LWMsgDataContext *context, LWMsgType *type, void *transmit_object, void *object, void *data)

A callback function type which converts a transmitted type to its presented form. The presented_object parameter will point to a block of memory large enough for the presented type. Any resources allocated to construct the presented object can be freed by the corresponding LWMsgTypeDestroyPresentedFunction

Parameters
[in]contextthe data context
[in]typethe type to marshal
[in]transmit_objectthe transmitted object
[out]presented_objectspace for the presented object
[in]datathe user data pointer specified to LWMSG_CUSTOM() or LWMSG_MEMBER_CUSTOM() in the type specification
Return values
LWMSG_STATUS_SUCCESSsuccess
...implementation-specific error
typedef void(* LWMsgTypeDestroyPresentedFunction)(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *data)

A callback function type which releases any resources associated with a presented object.

Parameters
contextthe data context
typethe type to free
objectthe address of the object to free
datathe user data pointer specified to LWMSG_CUSTOM() or LWMSG_MEMBER_CUSTOM() in the type specification
typedef void(* LWMsgTypeDestroyTransmittedFunction)(struct LWMsgDataContext *context, LWMsgType *type, void *object, void *data)

A callback function which releases any resources associated with a transmitted object.

Parameters
[in]contextthe data context
[in,out]objectthe transmitted object
[in]datathe user data pointer specified to LWMSG_CUSTOM() or LWMSG_MEMBER_CUSTOM() in the type specification
typedef LWMsgStatus(* LWMsgTypePrintFunction)(struct LWMsgDataContext *context, LWMsgType *attr, void *object, void *data, LWMsgBuffer *buffer)

A callback function type which prints the representation of a custom type, writing to the provided buffer.

Parameters
contextthe data context
objectthe address of the object to print
typethe type to print
datathe user data pointer specified to LWMSG_CUSTOM() or LWMSG_MEMBER_CUSTOM() in the type specification
bufferthe buffer into which to write
typedef size_t const LWMsgTypeSpec

The fundamental type used to represent a type specification. This is considered an implementation detail.

typedef LWMsgStatus(* LWMsgVerifyFunction)(struct LWMsgDataContext *context, LWMsgBool unmarshalling, void *object, void *data)

A callback function which performs verification of in-memory data immediately before marshalling or immediately after unmarshalling.

Parameters
contextthe data context
unmarshallingtrue when the operation being performed is unmarshalling
objectthe object to verify
datathe user data pointer given to LWMSG_ATTR_VERIFY()
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDthe object did not pass verification

Enumeration Type Documentation

Indicates whether an integer type is signed or unsigned.

Enumerator
LWMSG_SIGNED 

Signed

LWMSG_UNSIGNED 

Unsigned

Describes set/unset attributes of a type

Enumerator
LWMSG_TYPE_FLAG_NOT_NULL 

Type may not be NULL

LWMSG_TYPE_FLAG_SENSITIVE 

Type contains sensitive data

LWMSG_TYPE_FLAG_PROMOTED 

Type was implicitly promoted to a pointer

LWMSG_TYPE_FLAG_RANGE 

Type has a range constraint

LWMSG_TYPE_FLAG_ALIASABLE 

Pointer type is aliasable

Function Documentation

LWMsgTypeFlags lwmsg_type_get_flags ( const LWMsgType type)

Gets the flags for the specified type.

Parameters
[in]typethe type
Returns
the flags for the type
size_t lwmsg_type_get_custom_flags ( const LWMsgType type)

Gets custom flags for the specified type.

Parameters
[in]typethe type
Returns
custom flags for the type
LWMsgStatus lwmsg_type_get_integer_range ( const LWMsgType type,
size_t *  low,
size_t *  high 
)

Gets the bounds of an integer type. The specified type must be an integer type and must have the LWMSG_TYPE_FLAG_RANGE flag set.

Parameters
[in]typethe type
[out]lowthe lowest allowed value
[out]highthe highest allowed value
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_INVALID_PARAMETERthe type was not an integer or did not have a range set