class safmq::MQConnection

A class for connecting to a SAFMQ message queue server

Child Classes

A class for connecting to a SAFMQ message queue server

This class has no child classes.

ErrorCode AddUserIdentity(const std::string& subjectDN, const std::string& issuerDN, const std::string& username): Adds an X509 digitital certificate identity mapping.
ErrorCode AdvanceCursor(MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID): Advances the cursor to the next message in the queue
ErrorCode BeginTransaction(): Begins a transaction on the SAFMQ server.
ErrorCode CloseCursor(MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID): Closes a previously opened message cursor
ErrorCode CloseQueue(MQConnection::QueueHandle qhandle): Closes an already opened queue handle.
ErrorCode CommitTransaction(): Commits a transaction on the SAFMQ server, but leaves the transaction open.
ErrorCode CreateGroup(const std::string& groupname): Creates a user group.
ErrorCode CreateQueue(const std::string& queuename): Creates a new message queue
ErrorCode CreateTempQueue(std::string& tmpQueueName, MQConnection::QueueHandle& tmpQueue): Creates a new temporary message queue.
ErrorCode CreateUser(const std::string& username, const std::string& password, const std::string& description): Creates a user account on the safmq server
ErrorCode DeleteGroup(const std::string& groupname): Removes a user group
ErrorCode DeleteQueue(const std::string& queuename): Removes a message queue.
ErrorCode DeleteUser(const std::string& username): Removes a user account
ErrorCode EndTransaction(): Closes and commits a transaction on the SAMFQ server.
ErrorCode Enqueue(MQConnection::QueueHandle qhandle, QueueMessage& msg): Places the message msg on the queue specified by qhandle
ErrorCode EnqueueWithRelay(const std::string& destination_url, QueueMessage& msg): Enqueues a message for message relay forwarding to another queue/queue server.
ErrorCode EnumerateGroups(MQConnection::NAME_VECTOR& groups): Lists all groups on the safmq server
ErrorCode EnumerateQueues(MQConnection::QDATA_VECTOR& qnames): List all queues on the safmq server
ErrorCode EnumerateUserIdentities(const std::string& username, std::vector<safmq::X509Identity>& ids): Lists a set of X509 subject name and issuer names associated with the passed SAFMQ user login id
ErrorCode EnumerateUsers(MQConnection::USER_VECTOR& users): Lists all users on the safmq server
ErrorCode GetClientInfo(std::list<ClientInfo>& clients): Retreives information about connected clients
ErrorCode GetQueueStatistics(MQConnection::QueueHandle qhandle, bool includeStorageBytes, bool includeMessageBytes, QueueStatistics& stats): Retrieves performance statistics for a specific queue
ErrorCode GetServerStatistics(QueueStatistics& stats): Retrieves performance statistics for an entire server
ErrorCode GroupAddUser(const std::string& groupname, const std::string& username): Adds a user to a user group
ErrorCode GroupDeleteUser(const std::string& groupname, const std::string& username): Removes a user from a user group
ErrorCode GroupGetPermissions(const std::string& groupname, bool& modifyqueues, bool& modifyusers, bool& modifygroups): Retreives a user group's user access permissions
ErrorCode GroupGetUsers(const std::string& groupname, MQConnection::NAME_VECTOR& users): Retrieves a list of users in a user group
ErrorCode GroupSetPermissions(const std::string& groupname, bool modifyqueues, bool modifyusers, bool modifygroups): Sets user group access permissions for a user group
MQConnection(tcpsocket::socstream* server, const std::string& username, const std::string& password) throw(ErrorCode): Constructs a construction object and establishes a connection to a safmq server
ErrorCode OpenCursor(MQConnection::QueueHandle qhandle, MQConnection::CursorHandle& cursorID): Opens a message cursor for iterating through a message queue.
ErrorCode OpenQueue(const std::string& queuename, MQConnection::QueueHandle& qhandle): Opens a message queue for reading and writing
ErrorCode PeekCursor(MQConnection::QueueHandle qhandle, bool retrievebody, MQConnection::CursorHandle cursorID, QueueMessage& msg): Retreives a message from the safmq server located by the passed cursor to the passed id and leaves it in the queue
ErrorCode PeekFront(MQConnection::QueueHandle qhandle, bool retrievebody, SAFMQ_INT32 timeoutseconds, QueueMessage& msg): Retreives a message from the safmq server and leaves it in the queue
ErrorCode PeekID(MQConnection::QueueHandle qhandle, bool retrievebody, uuid& id, SAFMQ_INT32 timeoutseconds, QueueMessage& msg): Retreives a message from the safmq server with a recipt id equal to the passed id and leaves it in the queue
ErrorCode QueueDeleteGroupPermission(const std::string& queuename, const std::string& groupname): Removes user account's permissions for accessing a queue.
ErrorCode QueueDeleteUserPermission(const std::string& queuename, const std::string& username): Removes user account's permissions for accessing a queue.
ErrorCode QueueEnumeratePermissions(const std::string& queuename, std::vector<QueuePermissions>& perms): Retreives a list of permissions for a given queue
ErrorCode QueueSetGroupPermission(const std::string& queuename, const std::string& groupname, bool rd, bool wr, bool destroy, bool changesecurity): Sets a user groups's permissions for accessing a queue.
ErrorCode QueueSetUserPermission(const std::string& queuename, const std::string& username, bool rd, bool wr, bool destroy, bool changesecurity): Sets a user account's permissions for accessing a queue.
ErrorCode RemoveUserIdentity(const std::string& subjectDN, const std::string& issuerDN): Removes an X509 digitital certificate identity mapping.
ErrorCode Retrieve(MQConnection::QueueHandle qhandle, bool retrievebody, SAFMQ_INT32 timeoutseconds, QueueMessage& msg): Retreives a message from the safmq server and removes it from the queue
ErrorCode RetrieveCursor(MQConnection::QueueHandle qhandle, bool retrievebody, MQConnection::CursorHandle cursorID, QueueMessage& msg): Retreives a message from the safmq server located by the passed cursor to the passed id and removes it from the queue
ErrorCode RetrieveID(MQConnection::QueueHandle qhandle, bool retrievebody, uuid& id, SAFMQ_INT32 timeoutseconds, QueueMessage& msg): Retreives a message from the safmq server with a recipt id equal to the passed id and removes it from the queue
ErrorCode RollbackTransaction(): Rolls back a transaction on the SAFMQ server.
ErrorCode SeekID(MQConnection::QueueHandle qhandle, uuid& id, SAFMQ_INT32 timeoutseconds, MQConnection::CursorHandle cursorID): Locates a message from the safmq server with a recipt id equal to the passed id and points the cursor at it
ErrorCode SetPassword(const std::string& username, const std::string& password): Sets/Changes the password for a user account
ErrorCode TestCursor(MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID): Determines if a cursor is valid
ErrorCode UserGetGroups(const std::string& username, MQConnection::NAME_VECTOR& groups): Retrieves a list of user groups the user belongs to
ErrorCode UserGetPermissions(const std::string& username, bool& modifyqueues, bool& modifyusers, bool& modifygroups): Retreives a users user access permissions
ErrorCode UserSetPermissions(const std::string& username, bool modifyqueues, bool modifyusers, bool modifygroups): Sets user access permissions for an account
~MQConnection(): Closes the connection to the server and deallocates resourceses associated with this MQConnection.

Member Documentation

MQConnection (tcpsocket::socstream* server, const std::string& username, const std::string& password) throw(ErrorCode)

Constructs a construction object and establishes a connection to a safmq server


Parameters:: server - [in] A stream connected to the server
- username The user logging into this server
password - The password assoicated with the user logging into this server

~MQConnection ()

Closes the connection to the server and deallocates resourceses associated with this MQConnection. Destroying the connection also closes all associated queues and cursors.

Additionally destroying the connection rollsback and ends any pending transactions. Thus if the following occurs:

MQConnection* con  = new MQConnection("safmq://myserver","my name","my password");
MessageQueue* que = new MessageQueue(con,"my queue");
QueueMessage	msg;

con->BeginTransaction();
que->Retrieve(true,-1,msg);
delete queue;
delete con;

The net effect of the snippet is to retrieve the first message from the queue, then roll back the transaction as if con->RollbackTransaction() was called, then close the queue and connection to the server.

ErrorCode OpenQueue (const std::string& queuename, MQConnection::QueueHandle& qhandle)

Opens a message queue for reading and writing


Parameters:: queuename - [in] The name of the queue to open
qhandle - [out] Receives the handle to the newly opened queue
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST, EC_FORWARDNOTALLOWED

ErrorCode CloseQueue (MQConnection::QueueHandle qhandle)

Closes an already opened queue handle. Closing a queue also closes all associated cursors.


Parameters:: qhandle - [in] The queue handle to close
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTOPEN

ErrorCode GetQueueStatistics (MQConnection::QueueHandle qhandle, bool includeStorageBytes, bool includeMessageBytes, QueueStatistics& stats)

Retrieves performance statistics for a specific queue


Parameters:: qhandle - [in] A handle to an open queue
includeStorageBytes - [in] Requests storage bytes (on disk including purged messages) returned
includeMessageBytes - [in] Requests message bytes, bytes in queue (excluding purged messages)
stats - [out] Statistics about a queue
Returns:: EC_NOERROR, EC_NOTOPEN, EC_NETWORKERROR

ErrorCode GetServerStatistics (QueueStatistics& stats)

Retrieves performance statistics for an entire server


Parameters:: stats - [out] Statistics about a queue
Returns:: EC_NOERROR, EC_NOTOPEN, EC_NETWORKERROR

ErrorCode GetClientInfo (std::list<ClientInfo>& clients)

Retreives information about connected clients


Parameters:: clients - [out] List of connected clients
Returns:: EC_NOERROR, EC_NETWORKERROR

ErrorCode EnqueueWithRelay (const std::string& destination_url, QueueMessage& msg)

Enqueues a message for message relay forwarding to another queue/queue server. After completion, the return code will be EC_NOERROR on success and the msg's timestamp and message will have been set. It is important to note if the resposne queue name is not set, any errors from the final destination queue/queue server will be lost. It is suggested to use roundtripping unless error determination is not required, otherwise errors generated by the final destination server such as:

EC_DOESNOTEXIST

EC_NOTAUTHORIZED

EC_WRONGMESSAGETYPE

EC_NOTOPEN

EC_FORWARDNOTALLOWED

EC_DUPLICATEMSGID

will not returned to the client.


Parameters:: url - A safmq url in the format safmq://user:password@server:port/queuename -or- for ssl safmqs://user:password@server:port/queuename.
Note: the port specification is optional.
msg - The message to be sent.
Returns:: EC_NOERROR on success EC_INVALIDNAME incase of an invalid url
EC_NETWORKERROR
EC_NOTAUTHORIZED
EC_NOTOPEN
EC_WRONGMESSAGETYPE
EC_FORWARDNOTALLOWED

ErrorCode Enqueue (MQConnection::QueueHandle qhandle, QueueMessage& msg)

Places the message msg on the queue specified by qhandle


Parameters:: qhandle - [in] A handle to a previously opened queue
msg - [in/out] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_WRONGMESSAGETYPE

ErrorCode Retrieve (MQConnection::QueueHandle qhandle, bool retrievebody, SAFMQ_INT32 timeoutseconds, QueueMessage& msg)

Retreives a message from the safmq server and removes it from the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
timeoutseconds - [in] The number of seconds to wait for a message to be published on the queue in the case the queue is empty. -1 causes an indefinate wait.
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_NOMOREMESSAGES, EC_TIMEDOUT

ErrorCode RetrieveID (MQConnection::QueueHandle qhandle, bool retrievebody, uuid& id, SAFMQ_INT32 timeoutseconds, QueueMessage& msg)

Retreives a message from the safmq server with a recipt id equal to the passed id and removes it from the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
id - [in] The uuid recipt id of a message to search for in the message queue
timeoutseconds - [in] The number of seconds to wait for a message to be published on the queue in the case the queue is empty. -1 causes an indefinate wait.
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_TIMEDOUT

ErrorCode RetrieveCursor (MQConnection::QueueHandle qhandle, bool retrievebody, MQConnection::CursorHandle cursorID, QueueMessage& msg)

Retreives a message from the safmq server located by the passed cursor to the passed id and removes it from the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
cursorID - [in] The id of a queue cursor point to the message to be retreived
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTOPEN, EC_INVALIDCURSOR

ErrorCode PeekFront (MQConnection::QueueHandle qhandle, bool retrievebody, SAFMQ_INT32 timeoutseconds, QueueMessage& msg)

Retreives a message from the safmq server and leaves it in the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
timeoutseconds - [in] The number of seconds to wait for a message to be published on the queue in the case the queue is empty. -1 causes an indefinate wait.
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_NOMOREMESSAGES, EC_TIMEDOUT

ErrorCode PeekID (MQConnection::QueueHandle qhandle, bool retrievebody, uuid& id, SAFMQ_INT32 timeoutseconds, QueueMessage& msg)

Retreives a message from the safmq server with a recipt id equal to the passed id and leaves it in the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
id - [in] The uuid recipt id of a message to search for in the message queue
timeoutseconds - [in] The number of seconds to wait for a message to be published on the queue in the case the queue is empty. -1 causes an indefinate wait.
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_TIMEDOUT

ErrorCode PeekCursor (MQConnection::QueueHandle qhandle, bool retrievebody, MQConnection::CursorHandle cursorID, QueueMessage& msg)

Retreives a message from the safmq server located by the passed cursor to the passed id and leaves it in the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
retreivebody - [in] Flags the server to retreive the message body
cursorID - [in] The id of a queue cursor point to the message to be retreived
msg - [in] The message to be sent to the server, the message id and timestamp will be set by the server upon success
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTOPEN, EC_INVALIDCURSOR

ErrorCode OpenCursor (MQConnection::QueueHandle qhandle, MQConnection::CursorHandle& cursorID)

Opens a message cursor for iterating through a message queue. The cursor is positioned initially at the first message in the queue.


Parameters:: qhandle - [in] A handle to a previously opened queue
cursorID - [out] Receives the id of the new cursor
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_NOTOPEN

ErrorCode CloseCursor (MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID)

Closes a previously opened message cursor


Parameters:: qhandle - [in] A handle to a previously opened queue
cursorID - [in] The id of the cursor to close
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTOPEN

ErrorCode AdvanceCursor (MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID)

Advances the cursor to the next message in the queue


Parameters:: qhandle - [in] A handle to a previously opened queue
cursorID - [in] The id of the cursor to advance
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTOPEN, EC_NOMOREMESSAGES

ErrorCode SeekID (MQConnection::QueueHandle qhandle, uuid& id, SAFMQ_INT32 timeoutseconds, MQConnection::CursorHandle cursorID)

Locates a message from the safmq server with a recipt id equal to the passed id and points the cursor at it


Parameters:: qhandle - [in] A handle to a previously opened queue
id - [in] The uuid recipt id of a message to search for in the message queue
timeoutseconds - [in] The number of seconds to wait for a message to be published on the queue in the case the queue is empty. -1 causes an indefinate wait.
cursorID - [in] The id of the cursor to advance
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_TIMEDOUT

ErrorCode TestCursor (MQConnection::QueueHandle qhandle, MQConnection::CursorHandle cursorID)

Determines if a cursor is valid


Parameters:: qhandle - [in] A handle to a previously opened queue
cursorID - [in] A previously opened cursor
Returns:: EC_NETWORKERROR, EC_NOTOPEN, EC_INVALIDCURSOR

ErrorCode BeginTransaction ()

Begins a transaction on the SAFMQ server. If a call to CommitTransaction() or EndTransaction() is not made before destrying the connection, the transaction is rolled back to the state before calling BeginTransaction().


Returns:: EC_NETWORKERROR, EC_NOERROR if successful, EC_ALREADYOPEN if a transaction is already open
See Also:: EndTransaction() -- To close the transaction
CommitTransaction() -- To commit the transaction without closing it.

ErrorCode CommitTransaction ()

Commits a transaction on the SAFMQ server, but leaves the transaction open. No reading or writing from the queues is completed until the transaction is committed. This command causes any pending transactions to be performed.


Returns:: EC_NETWORKERROR,EC_NOERROR if successful

ErrorCode RollbackTransaction ()

Rolls back a transaction on the SAFMQ server. This command undoes any uncommited transactions (calls to Enqueue(), Retrieve(), RetrieveID(), or RetrieveCursor()).


Returns:: EC_NETWORKERROR, EC_NOERROR

ErrorCode EndTransaction ()

Closes and commits a transaction on the SAMFQ server. No reading or writing from the queues is completed until the transaction is committedCauses any pending transactions to be performed.


Returns:: EC_NETWORKERROR, EC_NOERROR, EC_NOTOPEN

ErrorCode EnumerateQueues (MQConnection::QDATA_VECTOR& qnames)

List all queues on the safmq server


Parameters:: qnames - [out] Receives the list of queue names
Returns:: EC_NOERROR, EC_NETWORKERROR

ErrorCode EnumerateUsers (MQConnection::USER_VECTOR& users)

Lists all users on the safmq server


Parameters:: users - [out] The list of user ids and logins
Returns:: EC_NOERROR, EC_NETWORKERROR

ErrorCode EnumerateGroups (MQConnection::NAME_VECTOR& groups)

Lists all groups on the safmq server


Parameters:: groups - [out] The list of group ids
Returns:: EC_NOERROR, EC_NETWORKERROR

ErrorCode CreateUser (const std::string& username, const std::string& password, const std::string& description)

Creates a user account on the safmq server


Parameters:: - username [in] The user id of the user account
password - [in] The account's password
- description [in] The description of the account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_ALREADYDEFINED, EC_NOTAUTHORIZED

ErrorCode DeleteUser (const std::string& username)

Removes a user account


Parameters:: - username [in] The user id of the user account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST

ErrorCode UserSetPermissions (const std::string& username, bool modifyqueues, bool modifyusers, bool modifygroups)

Sets user access permissions for an account


Parameters:: - username [in] The user id to modify permissions
modifyqueues - [in] Allows the user to add and remove queues
modifyusers - [in] Allows the user to add and remove users
modifygroups - [in] Allows the suer to add and remove groups
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST

ErrorCode UserGetPermissions (const std::string& username, bool& modifyqueues, bool& modifyusers, bool& modifygroups)

Retreives a users user access permissions


Parameters:: - username [in] The user id of the acount
modifyqueues - [out] Flags whether the user may add and remove queues
modifyusers - [out] Flags whether the user may add and remove users
modifygroups - [out] Flags whether the user may add and remove groups
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST

ErrorCode SetPassword (const std::string& username, const std::string& password)

Sets/Changes the password for a user account


Parameters:: - username [in] The user id of the acount
password - [in] The new password for the account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST

ErrorCode CreateGroup (const std::string& groupname)

Creates a user group. User groups can have rights like users, allowing multiple users to have the same security profile.


Parameters:: groupname - [in] The name of the group to create
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_ALREADYDEFINED

ErrorCode DeleteGroup (const std::string& groupname)

Removes a user group


Parameters:: groupname - [in] The name of the group to remove
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST

ErrorCode GroupSetPermissions (const std::string& groupname, bool modifyqueues, bool modifyusers, bool modifygroups)

Sets user group access permissions for a user group


Parameters:: groupname - [in] The name of the user group
modifyqueues - [in] Allows the group to add and remove queues
modifyusers - [in] Allows the group to add and remove users
modifygroups - [in] Allows the group to add and remove groups
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED, EC_DOESNOTEXIST

ErrorCode GroupGetPermissions (const std::string& groupname, bool& modifyqueues, bool& modifyusers, bool& modifygroups)

Retreives a user group's user access permissions


Parameters:: groupname - [in] The name of the user group
modifyqueues - [out] Flags whether the user may add and remove queues
modifyusers - [out] Flags whether the user may add and remove users
modifygroups - [out] Flags whether the user may add and remove groups
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST

ErrorCode GroupAddUser (const std::string& groupname, const std::string& username)

Adds a user to a user group


Parameters:: groupname - [in] The name of the user group
- username [in] The name of the user account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST, EC_NOTAUTHORIZED

ErrorCode GroupDeleteUser (const std::string& groupname, const std::string& username)

Removes a user from a user group


Parameters:: groupname - [in] The name of the user group
- username [in] The name of the user account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST, EC_NOTAUTHORIZED

ErrorCode GroupGetUsers (const std::string& groupname, MQConnection::NAME_VECTOR& users)

Retrieves a list of users in a user group


Parameters:: groupname - [in] The name of the user group
users - [out] The list of users id's in the group
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST

ErrorCode UserGetGroups (const std::string& username, MQConnection::NAME_VECTOR& groups)

Retrieves a list of user groups the user belongs to


Parameters:: - username [in] The user id
groups - [in] The list of groups the user belongs to
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_DOESNOTEXIST

ErrorCode CreateQueue (const std::string& queuename)

Creates a new message queue


Parameters:: queuename - [in] The name of the queue to create.
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_ALREADYDEFINED, EC_NOTAUTHORIZED

ErrorCode CreateTempQueue (std::string& tmpQueueName, MQConnection::QueueHandle& tmpQueue)

Creates a new temporary message queue. The queue is removed from the server once all clients close their handles to the queue, explicitly or implicity by disconnecting from the server.
After calling CreateTempQueue the SAFMQ server has created a queue, flagged as temporary, returns the server generated name of the queue, and a handle to that queue. Closing the queue removes it from the system, there is no need to explicitly delete it. Using the Closing technique, it is possible that the queue may remain open, because other clients have access to the queue.


Parameters:: tmpQueueName - [out] Receives the name of the temporary queue, relative to the server, when supplying this queue name to other clients, the server URL must be prepended to the name. i.e. If the url safmq://localhost was used to open the connection use "safmq://localhost/" + tmpQueue when supplying the queue name to other clients.
tmpQueue - [out] Receives a handle to the open queue
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_ALREADYDEFINED, EC_NOTAUTHORIZED

ErrorCode DeleteQueue (const std::string& queuename)

Removes a message queue. The command will fail in the case the queue is already opened by another user.


Parameters:: queuename - [in] The name of the message queue
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_QUEUEOPEN, EC_NOTAUTHORIZED

ErrorCode QueueSetUserPermission (const std::string& queuename, const std::string& username, bool rd, bool wr, bool destroy, bool changesecurity)

Sets a user account's permissions for accessing a queue. With out permissions, the user is assumed to have no access rights to the queue.


Parameters:: queuename - [in] The name of the queue
- username [in] The name of a user account
rd - [in] Allows the user to read from the queue
wr - [in] Allows the user to write tot he queue
- destroy [in] Allows the user to delete the queue
changesecurity - [in] Allows the user to reconfigure the queue's security
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED

ErrorCode QueueDeleteUserPermission (const std::string& queuename, const std::string& username)

Removes user account's permissions for accessing a queue. With out permissions, the user is assumed to have no access rights to the queue.


Parameters:: queuename - [in] The name of the queue
- username [in] The name of a user account
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED

ErrorCode QueueSetGroupPermission (const std::string& queuename, const std::string& groupname, bool rd, bool wr, bool destroy, bool changesecurity)

Sets a user groups's permissions for accessing a queue. With out permissions, the group is assumed to have no access rights to the queue.


Parameters:: queuename - [in] The name of the queue
groupname - [in] The name of a user group
rd - [in] Allows the group to read from the queue
wr - [in] Allows the group to write tot he queue
- destroy [in] Allows the group to delete the queue
changesecurity - [in] Allows the group to reconfigure the queue's security
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED

ErrorCode QueueDeleteGroupPermission (const std::string& queuename, const std::string& groupname)

Removes user account's permissions for accessing a queue. With out permissions, the group is assumed to have no access rights to the queue.


Parameters:: queuename - [in] The name of the queue
groupname - [in] The name of a user group
Returns:: EC_NOERROR, EC_NETWORKERROR, EC_NOTAUTHORIZED

ErrorCode QueueEnumeratePermissions (const std::string& queuename, std::vector<QueuePermissions>& perms)

Retreives a list of permissions for a given queue


Parameters:: queuename - [in] The name of the queue
perms - [out] Receives the list of permissions
Returns:: EC_NOERROR, EC_NETWORKERROR
See Also:: QueuePermissions

ErrorCode AddUserIdentity (const std::string& subjectDN, const std::string& issuerDN, const std::string& username)

Adds an X509 digitital certificate identity mapping. This method should be used to provide for a passwordless authentication using SSL and X509 digital certificates.

Example: (the sample X509 certificate shipped with SAFMQ source)

Subject: C=US, ST=Nebraska, L=Omaha, O=SAFMQ, CN=Matthew Battey/emailAddress=mattbattey@users.sourceforge.net
Issuer:  C=US, ST=Nebraska, L=Omaha, O=SAFMQ, CN=Matthew Battey/emailAddress=mattbattey@users.sourceforge.net

Thawte's Issuer DN:

Issuer: C=ZA, ST=Western Cape, L=Cape Town, O=Thawte Consulting cc, OU=Certification Services Division, CN=Thawte Premium Server CA/emailAddress=premium-server@thawte.com

In this case the issuer and subject are the same value, because the certificate shipped with SAFMQ is a "self-signed" certificate. Typically the Subject DN will be set by you and the Issuer DN will be determined by the organization certifying the authenticity of the certificate's origin.

Note: The Java implentation produces distinguished name strings in reverse order in comparison to the default output from tools like OpenSSL. SAFMQ uses OpenSSL so these must be in the order that OpenSSL would report the value pair order.


Parameters:: - subjectDN [in] the Subject Distinguished Name of the certificate
- issuerDN [in] the Issuer Distinguished Name of the certificate
- username [in] the target SAFMQ login id (username)
Returns:: EC_NOERROR upon success, EC_DOESNOTEXIST if the user ID does not exist, EC_NOTAUTHORIZED, EC_NETWORKERROR

ErrorCode RemoveUserIdentity (const std::string& subjectDN, const std::string& issuerDN)

Removes an X509 digitital certificate identity mapping. This method should be used to provide for a passwordless authentication using SSL and X509 digital certificates.


Parameters:: - subjectDN [in] the Subject Distinguished Name of the certificate
- issuerDN [in] the Issuer Distinguished Name of the certificate
Returns:: EC_NOERROR upon success, EC_DOESNOTEXIST if the user ID does not exist, EC_NOTAUTHORIZED, EC_NETWORKERROR

ErrorCode EnumerateUserIdentities (const std::string& username, std::vector<safmq::X509Identity>& ids)

Lists a set of X509 subject name and issuer names associated with the passed SAFMQ user login id


Parameters:: - username [in] The user name used to search for X509 identities.
ids - [out] This vector of safmq::X509Identity objects is populated upon successful return
Returns:: EC_NOERROR on success, EC_NETWORKERROR on network issue

Table of Contents HTML hierarchy of classes or Java