Persistent archives

Serialize messages to permanent storage. More...

Typedefs

typedef struct LWMsgArchive LWMsgArchive
 Archive handle. More...
 

Enumerations

enum  LWMsgArchiveDisposition {
  LWMSG_ARCHIVE_READ,
  LWMSG_ARCHIVE_WRITE,
  LWMSG_ARCHIVE_SCHEMA
}
 Archive file open disposition. More...
 

Functions

LWMsgStatus lwmsg_archive_new (const LWMsgContext *context, LWMsgProtocol *protocol, LWMsgArchive **archive)
 Create new archive handle. More...
 
LWMsgStatus lwmsg_archive_set_file (LWMsgArchive *archive, const char *filename, mode_t mode)
 Set file name and parameters. More...
 
LWMsgStatus lwmsg_archive_set_fd (LWMsgArchive *archive, int fd)
 Set file descriptor. More...
 
LWMsgStatus lwmsg_archive_set_byte_order (LWMsgArchive *archive, LWMsgByteOrder order)
 Set byte order. More...
 
void lwmsg_archive_set_protocol_update (LWMsgArchive *archive, LWMsgBool update)
 Set protocol update flag. More...
 
LWMsgStatus lwmsg_archive_open (LWMsgArchive *archive, LWMsgArchiveDisposition disp)
 Open archive file. More...
 
LWMsgStatus lwmsg_archive_close (LWMsgArchive *archive)
 Close archive file. More...
 
LWMsgStatus lwmsg_archive_write_message (LWMsgArchive *archive, LWMsgMessage *message)
 Write message into archive. More...
 
LWMsgStatus lwmsg_archive_read_message (LWMsgArchive *archive, LWMsgMessage *message)
 Read next message from archive. More...
 
LWMsgStatus lwmsg_archive_destroy_message (LWMsgArchive *archive, LWMsgMessage *message)
 Destroy a message. More...
 
void lwmsg_archive_delete (LWMsgArchive *archive)
 Delete archive handle. More...
 
LWMsgAssoclwmsg_archive_as_assoc (LWMsgArchive *archive)
 View archive as an association. More...
 

Detailed Description

Typedef Documentation

typedef struct LWMsgArchive LWMsgArchive

A handle used to open, read, write, and close archive files.

Enumeration Type Documentation

Disposition used to open an archive file.

Enumerator
LWMSG_ARCHIVE_READ 

Open archive for reading

LWMSG_ARCHIVE_WRITE 

Open archive for writing

LWMSG_ARCHIVE_SCHEMA 

Use archive schema

Function Documentation

LWMsgStatus lwmsg_archive_new ( const LWMsgContext context,
LWMsgProtocol protocol,
LWMsgArchive **  archive 
)

Creates a new handle for reading and writing archive files for the specified protocol.

Parameters
[in]contextan optional context
[in]protocola protocol specifying the available messages to be read and written
[out]archivethe archive handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_archive_set_file ( LWMsgArchive archive,
const char *  filename,
mode_t  mode 
)

Sets the archive file name and UNIX permissions for the given archive handle.

Parameters
[in,out]archivethe archive handle
[in]filenamethe path to the archive file
[in]modethe UNIX permissions used when creating a file that does not yet exist
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMsgStatus lwmsg_archive_set_fd ( LWMsgArchive archive,
int  fd 
)

Sets the file descriptor for the given archive handle.

Parameters
[in,out]archivethe archive handle
[in]fdthe file descriptor
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_archive_set_byte_order ( LWMsgArchive archive,
LWMsgByteOrder  order 
)

Sets the preferred byte order for archive file creation. This only has an effect when creating new archives.

Parameters
[in,out]archivethe archive handle
[in]orderthe byte order
Return values
LWMSG_STATUS_SUCCESSsuccess
void lwmsg_archive_set_protocol_update ( LWMsgArchive archive,
LWMsgBool  update 
)

Sets whether the protocol passed to lwmsg_archive_new() will be updated when schema information is read from an archive file. By default, the schema is merely checked against the protocol to ensure compatibility. If additional message types exist in the archive schema that are not in the protocol, opening the archive will fail as the application would be unable to handle these messages. If protocol updating is turned on, the protocol will instead be extended with the unknown message types and the open will succeed. This permanently modifies the protocol. The additional message types can be manipulated to a limited extent by the application with functions such as lwmsg_data_print_graph_alloc().

This only has an effect when an archive is opened for reading with the LWMSG_ARCHIVE_SCHEMA disposition bit set and the archive contains schema information.

Parameters
[in,out]archivethe archive handle
[in]updatewhether to update the protocol or not
LWMsgStatus lwmsg_archive_open ( LWMsgArchive archive,
LWMsgArchiveDisposition  disp 
)

Opens the underlying archive specified by lwmsg_archive_set_file() or lwmsg_archive_set_fd() with the specified disposition.

Parameters
[in,out]archivethe archive handle
[in]dispthe open disposition
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MEMORYout of memory
LWMSG_STATUS_MALFORMEDthe underlying file was malformed
LWMsgStatus lwmsg_archive_close ( LWMsgArchive archive)

Closes the underlying archive specified by lwmsg_archive_set_file() or lwmsg_archive_set_fd(). All written messages will be flushed.

Parameters
[in,out]archivethe archive handle
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMsgStatus lwmsg_archive_write_message ( LWMsgArchive archive,
LWMsgMessage message 
)

Write a message into an open archive.

Parameters
[in,out]archivethe archive handle
[in]messagethe message to write
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDthe provided message was malformed
LWMsgStatus lwmsg_archive_read_message ( LWMsgArchive archive,
LWMsgMessage message 
)

Reads the next message from an open archive.

Parameters
[in,out]archivethe archive handle
[out]messagethe read message
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDthe underlying file was malformed
LWMsgStatus lwmsg_archive_destroy_message ( LWMsgArchive archive,
LWMsgMessage message 
)

Frees all memory allocated for a message previously read from the given archive.

Parameters
[in]archivethe archive handle
[in,out]messagethe message to destroy
Return values
LWMSG_STATUS_SUCCESSsuccess
LWMSG_STATUS_MALFORMEDthe message was malformed
void lwmsg_archive_delete ( LWMsgArchive archive)

Deletes the given archive handle.

Parameters
[in,out]archivethe archive handle
LWMsgAssoc* lwmsg_archive_as_assoc ( LWMsgArchive archive)

Returns a "view" of the given archive handle as an association. The association may then be used as usual to "send" and "receive" messages, although some features (session, nonblocking operation) will not be available. Using lwmsg_assoc_delete() on the returned pointer is equivalent to deleting the archive handle.

Parameters
[in]archivethe archive handle
Returns
a view of the archive as an association