/**
* <summary>
* Retrieves the message pointed to by <c>cursorID</c>. The results
* are placed in the object <c>msg</c>.
* </summary>
*
* <remarks>
* <para>Note: Retrieved messages are removed from the queue.</para>
* </remarks>
*
* <param name="qhandle"> A handle to a queue previously opened by a call to OpenQueue(string)</param>
* <param name="retrievebody"> A flag indicating whether the body of the message should be retrieved</param>
* <param name="cursorID"> The cursor indicating the current position in the queue to be Read from</param>
* <param name="msg"> Receives the contents of the message.</param>
*
* <returns>Upon success a value of <c>ErrorCode.EC_NOERROR</c>, otherwise
* errors such as but not limited to could occur: <br/>
* <table border="0" cellpadding="3" cellspacing="0">
* <tr><td><c>ErrorCode.EC_NETWORKERROR</c></td>
* <td>A networking error has occurred and the conneciton
* is nolonger valid.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOMOREMESSAGES</c></td>
* <td>The queue is empty and no more messages are
* available.
* </td></tr>
* <tr><td><c>ErrorCode.EC_ALREADYCLOSED</c></td>
* <td>The queue reference is not valid as it has
* been closed.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTAUTHORIZED</c></td>
* <td>The user is not authorized to Read messages from this
* queue.
* </td></tr>
* <tr><td><c>ErrorCode.EC_CURSORINVALIDATED</c></td>
* <td>The cursor nolonger points to a valid location in the
* queue.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTOPEN</c></td>
* <td>The queue specified has not been opened by this connection.
* </td></tr>
* </table>
* </returns>
*
* <seealso cref="OpenQueue(string, QueueHandle)"/>
*/
public ErrorCode RetrieveCursor(QueueHandle qhandle, bool retrievebody, CursorHandle cursorID, QueueMessage msg)
{
ErrorCode ret = ErrorCode.EC_NOERROR;
PEEK_CURSOR_RETRIEVE_CURSOR_PARAMS parms = new PEEK_CURSOR_RETRIEVE_CURSOR_PARAMS();
parms.queueID = qhandle;
parms.retrievebody = (byte)(retrievebody?1:0);
parms.cursorID = cursorID;
try {
output.Write(Safmq.CMD_RETRIEVE_CURSOR);
parms.Write(output);
output.Flush();
ret = getResponseCode();
if (ret == ErrorCode.EC_NOERROR) {
msg.Read(input,retrievebody);
ret = ackRetrieveCursor(qhandle,msg);
}
} catch (Exception) {
ret = ErrorCode.EC_NETWORKERROR;
}
return ret;
}
/**
* <summary>
* Retrieves the message identified by <c>id</c> in the message's
* recipt id, set prior to the message having been enqueued (See:
* <c>Enqueue(QueueMessage)</c>. The results are placed in the object
* <c>msg</c>.
* </summary>
*
* <remarks>
* <para>Note: Message responsders will typically place the message id of the original
* message in the recipt id of the message being returned. This round-trip
* message identification is provided by SAFMQ as a method for coordinated two-way
* communications.</para>
*
* <para>Note: Retrieved messages are removed from the queue.</para>
* </remarks>
*
* <param name="qhandle"> A handle to a queue previously opened by a call to OpenQueue(string)</param>
* <param name="retrievebody"> A flag indicating whether the body of the message should be retrieved</param>
* <param name="id"> The UUID of the message to be retrieved.</param>
* <param name="timeoutseconds">
* The number of seconds to wait before returning, a value of zero (0) will
* cause the method to return immediately if no messages are present on the queue,
* a value of (-1) will cause the method to wait until a message is placed on the queue.</param>
* <param name="msg"> Receives the contents of the message.</param>
*
* <returns>Upon success a value of <c>ErrorCode.EC_NOERROR</c>, otherwise
* errors such as but not limited to could occur: <br/>
* <table border="0" cellpadding="3" cellspacing="0">
* <tr><td><c>ErrorCode.EC_NETWORKERROR</c></td>
* <td>A networking error has occurred and the conneciton
* is nolonger valid.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOMOREMESSAGES</c></td>
* <td>The queue is empty and no more messages are
* available.
* </td></tr>
* <tr><td><c>ErrorCode.EC_ALREADYCLOSED</c></td>
* <td>The queue reference is not valid as it has
* been closed.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTAUTHORIZED</c></td>
* <td>The user is not authorized to Read messages from this
* queue.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTOPEN</c></td>
* <td>The queue specified has not been opened by this connection.
* </td></tr>
* <tr><td><c>ErrorCode.EC_TIMEDOUT</c></td>
* <td>The operation timed out before a message became available.
* </td></tr>
* </table>
* </returns>
*
* <seealso cref="Enqueue(QueueHandle, QueueMessage)"/>
* <seealso cref="OpenQueue(string, QueueHandle)"/>
*/
public ErrorCode RetrieveID(QueueHandle qhandle, bool retrievebody, UUID id, int timeoutseconds, QueueMessage msg)
{
ErrorCode ret = ErrorCode.EC_NOERROR;
RETRIEVE_ID_PEEK_ID_PARAMS parms = new RETRIEVE_ID_PEEK_ID_PARAMS();
parms.queueID = qhandle;
parms.retrievebody = (byte)(retrievebody?1:0);
parms.reciptID = id;
parms.timeoutseconds = timeoutseconds;
try {
output.Write(Safmq.CMD_RETRIEVE_ID);
parms.Write(output);output.Flush();
ret = getResponseCode();
if (ret == ErrorCode.EC_NOERROR) {
msg.Read(input,retrievebody);
ret = ackRetrieveCursor(qhandle,msg);
}
} catch (IOException) {
ret = ErrorCode.EC_NETWORKERROR;
}
return ret;
}
/**
* <summary>
* Gathers the highest priority FIFO message present on the queue. The results
* are placed in the object <c>msg</c>. Any errors from the operation are
* returned on the stack. The message retrieved is <i>not</i> remvoed from the
* queue and is available for reading by other queue readers.
* </summary>
*
* <param name="qhandle"> A handle to a queue previously opened by a call to OpenQueue(string)</param>
* <param name="retrievebody"> A flag indicating whether the body of the message should be retrieved</param>
* <param name="timeoutseconds">The number of seconds to wait before returning, a value of zero (0) will
* cause the method to return immediately if no messages are present on the queue,
* a value of (-1) will cause the method to wait until a message is placed on the queue.
* </param>
* <param name="msg"> Receives the contents of the message.</param>
*
* <returns>Upon success a value of <c>ErrorCode.EC_NOERROR</c>, otherwise
* errors such as but not limited to could occur: <br/>
* <table border="0" cellpadding="3" cellspacing="0">
* <tr><td><c>ErrorCode.EC_NETWORKERROR</c></td>
* <td>A networking error has occurred and the conneciton
* is nolonger valid.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOMOREMESSAGES</c></td>
* <td>The queue is empty and no more messages are
* available.
* </td></tr>
* <tr><td><c>ErrorCode.EC_ALREADYCLOSED</c></td>
* <td>The queue reference is not valid as it has
* been closed.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTAUTHORIZED</c></td>
* <td>The user is not authorized to Read messages from this
* queue.
* </td></tr>
* <tr><td><c>ErrorCode.EC_NOTOPEN</c></td>
* <td>The queue specified has not been opened by this connection.
* </td></tr>
* <tr><td><c>ErrorCode.EC_TIMEDOUT</c></td>
* <td>The operation timed out before a message became available.
* </td></tr>
* </table>
* </returns>
*
* <seealso cref="OpenQueue(string, QueueHandle)"/>
*/
public ErrorCode PeekFront(QueueHandle qhandle, bool retrievebody, int timeoutseconds, QueueMessage msg)
{
ErrorCode ret = ErrorCode.EC_NOERROR;
RETRIEVE_PEEK_FRONT_PARAMS parms = new RETRIEVE_PEEK_FRONT_PARAMS();
parms.queueID = qhandle;
parms.retrievebody = (byte)(retrievebody?1:0);
parms.timeoutseconds = timeoutseconds;
try {
output.Write(Safmq.CMD_PEEK_FRONT);
parms.Write(output);
output.Flush();
ret = getResponseCode();
if (ret == ErrorCode.EC_NOERROR)
msg.Read(input,retrievebody);
} catch (Exception) {
ret = ErrorCode.EC_NETWORKERROR;
}
return ret;
}
