Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

Serialization
[Simple Objects C API]


Detailed Description

Functions for simple objects serialization and de-serialization.


Enumerations

enum  sobj_text_context {
  SOBJ_CTX_GENERAL = 1, SOBJ_CTX_SELECTION = 2, SOBJ_CTX_ARRAY = 3, SOBJ_CTX_EXPRESSION = 4,
  SOBJ_CTX_STRING = 5
}
 Enumeration of text serialization contexts. More...
enum  sobj_serialization_mode {
  SOBJ_SER_BINARY = 1, SOBJ_SER_TEXT = 2, SOBJ_SER_TEXT_COMPACT = 3, SOBJ_SER_TEXT_PRETTY = 4,
  SOBJ_SER_TEXT_DISPLAY = 5
}
 Enumeration of serialization modes. More...

Functions

size_t sobj_pack_ccode (struct sobj *sobj, struct sobj_buffer *buffer, bool binary, struct sobj_env *env)
 Serialize a simple object to a C expression.
sobjsobj_unpack (const char *ser, ptrdiff_t ser_len, enum sobj_text_context context, struct sobj_env *env)
 Deserialize a simple object.
sobjsobj_unpack_x (const char **ser, ptrdiff_t ser_len, enum sobj_text_context context, struct sobj_env *env)
 Deserialize a simple object.
sobjsobj_unpack_fp (FILE *fp, ptrdiff_t count, enum sobj_text_context context, struct sobj_env *env)
 Deserialize a simple object from a standard C stream.
int sobj_unpack_scan (int(*get_fn)(void *), void *sender, struct sobj_buffer *buffer, long limit)
 Scan for the end of a serialization of a simple object.
size_t sobj_pack (struct sobj *sobj, enum sobj_serialization_mode mode, struct sobj_buffer *buffer, struct sobj_env *env)
 Create a serialization from a simple object instance.
size_t sobj_pack_fp (struct sobj *sobj, enum sobj_serialization_mode mode, FILE *out, struct sobj_env *env)
 Create a serialization from a simple object instance.


Enumeration Type Documentation

enum sobj_serialization_mode
 

Enumeration of serialization modes.

Enumeration values:
SOBJ_SER_BINARY  Binary serialization.
SOBJ_SER_TEXT  Standard text serialization.
SOBJ_SER_TEXT_COMPACT  Compact text serialization.
SOBJ_SER_TEXT_PRETTY  Pretty printed text serialization.
SOBJ_SER_TEXT_DISPLAY  Text serialization used to display an object as-is.

This is like SOBJ_SER_TEXT_COMPACT, but without the ClassEnv::pack() (aka sobj_env_class::so_pack) callback being called.

enum sobj_text_context
 

Enumeration of text serialization contexts.

Enumeration values:
SOBJ_CTX_GENERAL  General context.
SOBJ_CTX_SELECTION  Selection context.
SOBJ_CTX_ARRAY  Array context.
SOBJ_CTX_EXPRESSION  Expression context.
SOBJ_CTX_STRING  String context.


Function Documentation

size_t sobj_pack struct sobj sobj,
enum sobj_serialization_mode  mode,
struct sobj_buffer buffer,
struct sobj_env env
 

Create a serialization from a simple object instance.

Before serialization, the so_pack() callback of the class environment is called.

Parameters:
sobj The called object.
mode This parameter specifies the serialization variant. This is one of SOBJ_SER_BINARY, SOBJ_SER_TEXT, SOBJ_SER_TEXT_COMPACT, SOBJ_SER_TEXT_PRETTY, SOBJ_SER_TEXT_DISPLAY. Specify SOBJ_SER_BINARY for a binary serialization and SOBJ_SER_TEXT for a default text serialization.
buffer The byte buffer receiving the serialization of the called object sobj. In case of a text serialization, a terminating null-byte is written to the buffer. The serialization is appended to the provided buffer object.
env The environment. This may be a null-pointer.
Returns:
The function returns length of the serialization (in bytes), in case of a text serialization not counting the terminating null-byte.

size_t sobj_pack_ccode struct sobj sobj,
struct sobj_buffer buffer,
bool  binary,
struct sobj_env env
 

Serialize a simple object to a C expression.

This function creates a C expression which evaluates to an object that is equal to the specified object.

Note:
The current implementation may call the ClassEnv::pack callback function twice. This may be fixed in a future version of the function if it turns out to be a problem.
Parameters:
sobj The caller object.
buffer The byte buffer receiving the expression generated from the called object sobj, including a terminating null-character. The serialization is appended to the provided buffer object.
binary Flag indicating the the function may use binary data strings in the generated code.
env The environment. This may be a null-pointer.
Returns:
The function returns the length of the C expression (in bytes), not counting the terminating null-character.

size_t sobj_pack_fp struct sobj sobj,
enum sobj_serialization_mode  mode,
FILE *  out,
struct sobj_env env
 

Create a serialization from a simple object instance.

This is a variant of the sobj_pack() function. Before serialization, the so_pack() callback of the class environment is called.

Parameters:
sobj The called object.
mode The serialization variant.
out A standard C stream object. The serialization is written to this stream. Note that the stream is not flushed after writing.
env The environment. This may be a null-pointer.
Returns:
The function returns length of the serialization (in bytes), in case of a text serialization not counting the terminating null-byte.

struct sobj* sobj_unpack const char *  ser,
ptrdiff_t  ser_len,
enum sobj_text_context  context,
struct sobj_env env
 

Deserialize a simple object.

The serialized representation may be text or binary (resolved automatically). After deserialization, the so_unpack() callback from the appropriate class environment is called.

Parameters:
ser The serialization of the simple object.
ser_len The length of the serialization (in bytes). For text serializations, -1 indicates a null-terminated serialization string.
context The serialization context. If the serialization ser is a binary serialization, the context parameter is ignored.
env The environment. This may be a null-pointer.
Returns:
On success, the deserialized object instance is returned. On error, a null-pointer is returned and the error indicatior so_error of the environment object env is set.

struct sobj* sobj_unpack_fp FILE *  fp,
ptrdiff_t  count,
enum sobj_text_context  context,
struct sobj_env env
 

Deserialize a simple object from a standard C stream.

The serialized representation may be text or binary (resolved automatically). After deserialization, the so_unpack() callback from the appropriate class environment is called (unless context is SOBJ_SER_TEXT_DISPLAY, which will prevent the callback).

Parameters:
fp The standard C stream.
count The maximum number of bytes being read from the stream. The special value -1 indicates that the entire file (i.e. up to the EOF) should be read.
context The serialization context. If the serialization ser is a binary serialization, the context parameter is ignored.
env The environment. This may be a null-pointer.
Returns:
On success, the deserialized object instance is returned. On error, a null-pointer is returned and the error indicatior so_error of the environment object env is set.
Note:
  • The function will read from the stream fp until the specified limit count or an EOF is reached. All data read from the stream is held in a temporarily allocated buffer.
  • Junk at the end of the serialization is silently ignored. Use the sobj_unpack_x() function to check for trailing junk in a serialization.
  • In case of a read error, a null pointer is returned, even if the data read so far is a complete and valid serialization.

int sobj_unpack_scan int(*)(void *)  get_fn,
void *  sender,
struct sobj_buffer buffer,
long  limit
 

Scan for the end of a serialization of a simple object.

The function will read characters from the specified input source until an entire simple object has been read. For text serializations, the scan operation will stop as soon as an unquoted semicolon is found (serialization separator).

If a read buffer is specified, then the data read will be appended to the specified buffer. In case of a text serialization, a terminating semicolon will also be appended to the buffer (even though it is not part of the serialization).

Note:
The only text serialization context supported is the general context (SOBJ_CTX_GENERAL).
Parameters:
get_fn Function for reading the next character. The function should return an integer value in the range 0 through 255 if a character was read, or -1 in case of an EOF or error. The argument passed to the function is the sender parameter passed to this function.
sender This value is passed as a parameter to the specified get_fn function.
buffer If this is not a null-pointer, then the data read through the specified get_fn function is appended to the specified buffer.
limit The maximum number of characters to be appended to the specified buffer. -1 for unlimited.
Return values:
0 Success.
-1 The get_fn function indicated an EOF or error (by returning the special value -1).

struct sobj* sobj_unpack_x const char **  ser,
ptrdiff_t  ser_len,
enum sobj_text_context  context,
struct sobj_env env
 

Deserialize a simple object.

The serialized representation may be text or binary (resolved automatically). After deserialization, the so_unpack() callback from the appropriate class environment is called.

Parameters:
ser Pointer to a variable pointing to the serialization of the simple object. On success, the value of *ser is set to point to the first character following the last character recognized (this may be the terminating null-character). In case of an error, the value of *ser is kept unchanged.
ser_len The length of the serialization (in bytes). For text serializations, -1 indicates a null-terminated serialization string.
context The serialization context. If the serialization ser is a binary serialization, the context parameter is ignored.
env The environment. This may be a null-pointer.
Returns:
On success, the deserialized object instance is returned. On error, a null-pointer is returned and the error indicatior so_error of the environment object env is set.


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1