Summary: Isode provides a number of APIs which allow integrators and product developers to build components that access the Isode Messaging server products or other products supporting the same protocols.
store.h File Reference

Switch Operation Management Interface: Message Store access. More...

#include "session.h"
#include "storeatt.h"

Go to the source code of this file.

Macros

#define SOM_FACILITY_STORE   (8)
 

Typedefs

typedef void SOMMSStoreCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSData *data, int status, const char *errstring)
 Prototype for callback for store operation completion. More...
 
typedef void SOMMSStoreMonitorCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSData *data, int status, const char *datap, size_t dlen)
 Prototype for callback for store monitoring. More...
 
typedef void SOMMSStoreMailboxesCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSData *data, int status)
 Prototype for callback for store mailboxes operation completion. More...
 
typedef void SOMMSStoreConnectionsCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSData *data, int status)
 Prototype for callback for store connections operation completion. More...
 
typedef void SOMMSStoreMessagesCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSData *data, int status)
 Prototype for callback for store messages operation completion. More...
 
typedef void SOMMSConnectionCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSConnection *con, int status)
 Prototype for callback for reporting connection object. More...
 
typedef void SOMMSMailboxCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSMailbox *mbx, int status)
 Prototype for callback for reporting mailbox object. More...
 
typedef void SOMMSMessageCallback(struct SOMSession *session, void *ophandle, void *clientdata, struct SOMMSMessage *message, int status)
 Prototype for callback for reporting message object. More...
 

Enumerations

enum  som_storemonitor { SOM_STORE_MONITOR_NONE, SOM_STORE_MONITOR_CONNECTIONS, SOM_STORE_MONITOR_MAILBOXES }
 
enum  som_storecontrol {
  SOM_STORE_ABORT, SOM_STORE_SHUTDOWN, SOM_STORE_RESTART, SOM_STORE_LOGOUT,
  SOM_STORE_BLOCK_OPERATION, SOM_STORE_UNBLOCK_OPERATION, SOM_STORE_MAXCONNS, SOM_STORE_MAXVOL,
  SOM_STORE_MAXMSGS, SOM_STORE_REBUILD_MAILBOX_LIST
}
 
enum  som_managemessage { SOM_STORE_MESSAGE_DELETE, SOM_STORE_MESSAGE_MOVE, SOM_STORE_MESSAGE_SETSTATE }
 
enum  som_managemailbox {
  SOM_STORE_MAILBOX_DELETE, SOM_STORE_MAILBOX_BACKUP, SOM_STORE_MAILBOX_RESTORE, SOM_STORE_MAILBOX_RESTORE_MESSAGE,
  SOM_STORE_MAILBOX_REGISTER_AUTOACTION, SOM_STORE_MAILBOX_DEREGISTER_AUTOACTION, SOM_STORE_TIDY_MAILBOX, SOM_STORE_REBUILD_STATS
}
 

Functions

int SOMStoreSetMonitorCallback (struct SOMSession *session, SOMMSStoreMonitorCallback *callback, SOMMSStoreMonitorCallback **oldvalue)
 Set the Store monitor callback function for this session. More...
 
int SOMStoreSetCallback (struct SOMSession *session, SOMMSStoreCallback *callback, SOMMSStoreCallback **oldvalue)
 Set the Store callback function for this session. More...
 
int SOMStoreSetListMailboxesCallback (struct SOMSession *session, SOMMSStoreMailboxesCallback *callback, SOMMSStoreMailboxesCallback **oldvalue)
 Set the Store "list mailboxes" callback function for this session. More...
 
int SOMStoreSetListConnectionsCallback (struct SOMSession *session, SOMMSStoreConnectionsCallback *callback, SOMMSStoreConnectionsCallback **oldvalue)
 Set the Store "list connections" callback function for this session. More...
 
int SOMStoreSetListMessagesCallback (struct SOMSession *session, SOMMSStoreMessagesCallback *callback, SOMMSStoreMessagesCallback **oldvalue)
 Set the Store "list messages" callback function for this session. More...
 
int SOMStoreSetConnectionCallback (struct SOMSession *session, SOMMSConnectionCallback *callback, SOMMSConnectionCallback **oldvalue)
 Set the callback function for connection objects for this session. More...
 
int SOMStoreSetMailboxCallback (struct SOMSession *session, SOMMSMailboxCallback *callback, SOMMSMailboxCallback **oldvalue)
 Set the callback function for mailboxes for this session. More...
 
int SOMStoreSetMessageCallback (struct SOMSession *session, SOMMSMessageCallback *callback, SOMMSMessageCallback **oldvalue)
 Set the callback function for messages for this session. More...
 
int SOMStoreGetStrParam (struct SOMSession *session, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return an string-valued parameter from the store object. More...
 
int SOMStoreGetIntParam (struct SOMSession *session, int paramtype, int *valp)
 Return an integer-valued parameter from the store object. More...
 
int SOMStoreConnectionGetStrParam (struct SOMMSConnection *connection, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return an string-valued parameter from the connection object. More...
 
int SOMStoreGetMailbox (struct SOMMSData *data, void **prev, char *buffer, size_t buflen, size_t *paramlenp)
 Return the next mailbox path from a data block. More...
 
int SOMStoreGetConnection (struct SOMMSData *data, void **prev, int *valp)
 Return the next connection id from a data block. More...
 
int SOMStoreGetMessage (struct SOMMSData *data, void **prev, char *buffer, size_t buflen, size_t *paramlenp)
 Return the next message path from a data block. More...
 
int SOMStoreConnectionGetIntParam (struct SOMMSConnection *con, int paramtype, int *valp)
 Return an integer-valued parameter from the connection object. More...
 
int SOMStoreMailboxGetStrParam (struct SOMMSMailbox *mbx, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return an string-valued parameter from the mailbox object. More...
 
int SOMStoreMailboxGetIntParam (struct SOMMSMailbox *mbx, int paramtype, int *valp)
 Return an integer-valued parameter from the mailbox object. More...
 
int SOMStoreMessageGetStrParam (struct SOMMSMessage *message, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return an string-valued parameter from the message object. More...
 
int SOMStoreMessageGetIntParam (struct SOMMSMessage *message, int paramtype, int *valp)
 Return an integer-valued parameter from the message object. More...
 
int SOMStoreMonitor (struct SOMSession *session, enum som_storemonitor type, void *ophandle, int async)
 Start monitoring store events. More...
 
int SOMStoreManageMailbox (struct SOMSession *session, enum som_managemailbox op, const char *mbx, const char *qualifier, const char *qual2, const char *qual3, void *ophandle, int async)
 Perform management operation on Mailbox. More...
 
int SOMStoreManageMessage (struct SOMSession *session, enum som_managemessage op, const char *source_mbx, int seqnum, const char *dest_mbx, void *ophandle, int async)
 Perform management operation on Message. More...
 
int SOMStoreForwardMessage (struct SOMSession *session, const char *source_mbx, int seqnum, const char *dest_addresses, const char *covernote, void *ophandle, int async)
 Forward a Message. More...
 
int SOMStoreControl (struct SOMSession *session, enum som_storecontrol control, char *qualifier, void *ophandle, int async)
 Perform control operation on Store. More...
 
int SOMStoreStatus (struct SOMSession *session, void *ophandle, int async)
 Get current Store status. More...
 
int SOMStoreConnectionStatus (struct SOMSession *session, int connectionid, void *ophandle, int async)
 Get connection status. More...
 
int SOMStoreMailboxStatus (struct SOMSession *session, char *mailbox, void *ophandle, int async)
 Get mailbox status. More...
 
int SOMStoreMessageStatus (struct SOMSession *session, char *mailbox, int seqno, void *ophandle, int async)
 Get message status. More...
 
int SOMStoreMailboxes (struct SOMSession *session, void *ophandle, int async)
 Get list of mailboxes in Store. More...
 
int SOMStoreConnections (struct SOMSession *session, void *ophandle, int async)
 Get list of connections to Store. More...
 
int SOMStoreMessages (struct SOMSession *session, char *mailbox, void *ophandle, int async)
 Get list of messages in a mailbox. More...
 

Detailed Description

Switch Operation Management Interface: Message Store access.

Note: Store operations return their results normally via a callback. Which callback this is depends on the data type. If the request returns multiple objects, then there will be multiple calls to the relevant callback.

Asynchronous operations return the overall operation status through the main callback. This is not called for synchronous operations.

The data on the Store itself is available (after a query operation) via the main session object.

Definition in file store.h.

Macro Definition Documentation

#define SOM_FACILITY_STORE   (8)

Mask use to request XMS facility

Definition at line 33 of file store.h.

Enumeration Type Documentation

The operations which can be performed on the Store itself.

Enumerator
SOM_STORE_ABORT 

Terminate Store immediately

SOM_STORE_SHUTDOWN 

Graceful shutdown of Store

SOM_STORE_RESTART 

Stop and restart Store

SOM_STORE_LOGOUT 

Logout all users

SOM_STORE_BLOCK_OPERATION 

Block an operation

SOM_STORE_UNBLOCK_OPERATION 

Unblock an operation

SOM_STORE_MAXCONNS 

Change number of connections allowed

SOM_STORE_MAXVOL 

Change max volume of messages allowed

SOM_STORE_MAXMSGS 

Change max number of messages allowed

Definition at line 529 of file store.h.

The operations which can be performed on messages within the Store.

Definition at line 549 of file store.h.

549  {
550  SOM_STORE_MESSAGE_DELETE,
551  SOM_STORE_MESSAGE_MOVE,
552  SOM_STORE_MESSAGE_SETSTATE
553 };

The operations which can be performed on mailboxes within the Store.

Definition at line 560 of file store.h.

560  {
561  SOM_STORE_MAILBOX_DELETE,
562  SOM_STORE_MAILBOX_BACKUP,
563  SOM_STORE_MAILBOX_RESTORE,
564  SOM_STORE_MAILBOX_RESTORE_MESSAGE,
565  SOM_STORE_MAILBOX_REGISTER_AUTOACTION,
566  SOM_STORE_MAILBOX_DEREGISTER_AUTOACTION,
567  SOM_STORE_TIDY_MAILBOX,
568  SOM_STORE_REBUILD_STATS
569 };

Function Documentation

int SOMStoreSetMonitorCallback ( struct SOMSession session,
SOMMSStoreMonitorCallback callback,
SOMMSStoreMonitorCallback **  oldvalue 
)

Set the Store monitor callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetCallback ( struct SOMSession session,
SOMMSStoreCallback callback,
SOMMSStoreCallback **  oldvalue 
)

Set the Store callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetListMailboxesCallback ( struct SOMSession session,
SOMMSStoreMailboxesCallback callback,
SOMMSStoreMailboxesCallback **  oldvalue 
)

Set the Store "list mailboxes" callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetListConnectionsCallback ( struct SOMSession session,
SOMMSStoreConnectionsCallback callback,
SOMMSStoreConnectionsCallback **  oldvalue 
)

Set the Store "list connections" callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetListMessagesCallback ( struct SOMSession session,
SOMMSStoreMessagesCallback callback,
SOMMSStoreMessagesCallback **  oldvalue 
)

Set the Store "list messages" callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetConnectionCallback ( struct SOMSession session,
SOMMSConnectionCallback callback,
SOMMSConnectionCallback **  oldvalue 
)

Set the callback function for connection objects for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetMailboxCallback ( struct SOMSession session,
SOMMSMailboxCallback callback,
SOMMSMailboxCallback **  oldvalue 
)

Set the callback function for mailboxes for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreSetMessageCallback ( struct SOMSession session,
SOMMSMessageCallback callback,
SOMMSMessageCallback **  oldvalue 
)

Set the callback function for messages for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMStoreManageMailbox ( struct SOMSession session,
enum som_managemailbox  op,
const char *  mbx,
const char *  qualifier,
const char *  qual2,
const char *  qual3,
void *  ophandle,
int  async 
)

Perform management operation on Mailbox.

Parameters
session[in] Pointer to address of session object
op[in] Enumerated value indicating the operation
mbx[in] Mailbox path
qualifier[in] Command qualifier
qual2[in] Secondary command qualifier
qual3[in] Tertiary command qualifier
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error
int SOMStoreManageMessage ( struct SOMSession session,
enum som_managemessage  op,
const char *  source_mbx,
int  seqnum,
const char *  dest_mbx,
void *  ophandle,
int  async 
)

Perform management operation on Message.

Parameters
session[in] Pointer to address of session object
op[in] Enumerated value indicating the operation
source_mbx[in] Source mailbox path
seqnum[in] Message sequence number
dest_mbx[in] Destination mailbox (for move operation)
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error
int SOMStoreForwardMessage ( struct SOMSession session,
const char *  source_mbx,
int  seqnum,
const char *  dest_addresses,
const char *  covernote,
void *  ophandle,
int  async 
)

Forward a Message.

Parameters
session[in] Pointer to address of session object
source_mbx[in] Source mailbox path
seqnum[in] Message sequence number
dest_addresses[in] Destination addresses
covernote[in] Cover note to include
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error
int SOMStoreControl ( struct SOMSession session,
enum som_storecontrol  control,
char *  qualifier,
void *  ophandle,
int  async 
)

Perform control operation on Store.

Parameters
session[in] Pointer to address of session object
control[in] Enumerated value indicating the operation
qualifier[in] Qualifier for operation
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error
int SOMStoreStatus ( struct SOMSession session,
void *  ophandle,
int  async 
)

Get current Store status.

Parameters
session[in] Pointer to address of session object
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

After a successful return, or in the callback routine if async., the Store data can be retrieved via the session object using SOMStoreGetStrParam and SOMStoreGetIntParam

int SOMStoreConnectionStatus ( struct SOMSession session,
int  connectionid,
void *  ophandle,
int  async 
)

Get connection status.

Parameters
session[in] Pointer to address of session object
connectionid[in] Identified for connection
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Connection data is returned via the callback.

int SOMStoreMailboxStatus ( struct SOMSession session,
char *  mailbox,
void *  ophandle,
int  async 
)

Get mailbox status.

Parameters
session[in] Pointer to address of session object
mailbox[in] Mailbox path
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Mailbox data is returned via the callback.

int SOMStoreMessageStatus ( struct SOMSession session,
char *  mailbox,
int  seqno,
void *  ophandle,
int  async 
)

Get message status.

Parameters
session[in] Pointer to address of session object
mailbox[in] Mailbox path
seqno[in] Message sequence number
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Message data is returned via the callback.

int SOMStoreMailboxes ( struct SOMSession session,
void *  ophandle,
int  async 
)

Get list of mailboxes in Store.

Parameters
session[in] Pointer to address of session object
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Data is returned via the callback.

int SOMStoreConnections ( struct SOMSession session,
void *  ophandle,
int  async 
)

Get list of connections to Store.

Parameters
session[in] Pointer to address of session object
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Data is returned via the callback.

int SOMStoreMessages ( struct SOMSession session,
char *  mailbox,
void *  ophandle,
int  async 
)

Get list of messages in a mailbox.

Parameters
session[in] Pointer to address of session object
mailbox[in] name of mailbox
ophandle[in] Value passed to callback
async[in] Operation is asynchronous if TRUE
Returns
zero on success; non-zero on error

Data is returned via the callback.