Minimalist Queue Services (MQS) - XML-RPC calls definition

Minimalist Queue Services (MQS) - Basic API definition

This document describes the XML-RPC calls available. We hope that in future the API will be available via some other protocol/interface.

valid for MQS version 0.0.9 and higher

mqs.GetMessage

Purpose: mqs.GetMessage permits to retrieve the next message from a specific queue. With a rdbms backend, the message is logically removed from the queue (flagged). With a flat file database backend, the message is really removed from the queue.
Call: mqs.GetMessage(string auth, string queue )

auth :: is the authentication string. For anomymous, the string should be empty.
queue :: is the queue name. This should be a valid queue name existing on the mqs server.

Return value: is the message itself if the queue is not empty.

mqs.GetMessageBulk

Purpose: mqs.GetMessageBulk permits to retrieve the next messages from a specific queue. With a rdbms backend, the messages are logically removed from the queue (flagged). With a flat file database backend, the messages are really removed from the queue.
Call: mqs.GetMessageBulk(string auth, string queue, int maxmessages )

auth :: is the authentication string. For anomymous, the string should be empty.
queue :: is the queue name. This should be a valid queue name existing on the mqs server.
maxmessages :: is an integer containing the maximum messages to return.

Return value: is an array containing the message(s).

mqs.SubmitMessage

Purpose: mqs.SubmitMessage permits to submit a message into a specific queue.
Call: mqs.SubmitMessage(string auth, string message, string queue, string cid, int priority )

auth :: is the authentication string. For anonymous, the string should be empty.
message :: is the message that will be pushed into the specific queue.
queue :: is the queue name specified for submitting the message.
cid :: is the correlation id. (not used for the moment)
priority :: is the priority of the message (an integer). The default priority for the queue will be used if priority is set to -1. (Ignored with a flat file backend)

Return value: 1 if the message is correctly stored in the queue.

mqs.SubmitMessageBulk

Purpose: mqs.SubmitMessageBulk permits to submit a message into a specific queue.
Call: mqs.SubmitMessageBulk(string auth, array message, string queue, string cid, int priority )

auth :: is the authentication string. For anonymous, the string should be empty.
message :: is the array of messages that will be pushed into the specific queue.
queue :: is the queue name specified for submitting the message.
cid :: is the correlation id. (not used for the moment)
priority :: is the priority of the message (an integer). The default priority for the queue will be used if priority is set to -1. (Ignored with a flat file backend)

Return value: 1 if the messages are correctly stored in the queue.

mqs.DeleteMessage

Purpose: mqs.DeleteMessage call removes the tagged message from a specific queue. The messages are tagged with the mqs.GetMessage call. This is generally used by the queue manager but this can used by some other application if required.
Call: mqs.DeleteMessage(string auth, string queue )

auth :: is the authentication string. For anonymous, the string should be empty.
queue :: is the queue name specified for deleting the tagged (retrieved) message.

Return value: is the number of deleted messages.

mqs.TestEcho

Purpose: mqs.TestEcho permits to test if the XML-RPC (or any other interface) is working on the mqs server. The procedure is returning the string passed as a parameter.
Call: mqs.TestEcho(string message )

Return value : the message itself.

Sample code

MQS Error Code

1 : Unknown queue.
2 : Empty queue. e.g. not messages are available for mqs.GetMessage.
3 : Permission denied.
100 : Undefined error.
3xx : Specific mqsd server error.

MQS url definition

General definition : mqs://protocol/host:port/auth/queue-name/

mqs :: is the fixed prefix to defined that is MQS.
protocol :: is the string defining the procotol to be used.
host:port :: is the string defining the hostname and the port required. If the protocol required it. If not 0:0 is used.
auth :: is the string defining the authentication mechanism.
queue-name :: is the string defining the name of the queue.

License

Copyright (C) 2003,2004 Alexandre Dulaunoy <adulau@foo.be>

This program is  free software; you can redistribute  it and/or modify
it under the  terms of the GNU General Public  License as published by
the Free Software Foundation; either  version 2 of the License, or (at
your option) any later version. 

This program  is distributed in the  hope that it will  be useful, but
WITHOUT   ANY  WARRANTY;   without  even   the  implied   warranty  of
MERCHANTABILITY  or FITNESS  FOR A  PARTICULAR PURPOSE.   See  the GNU
General Public License for more details. 

You  should have received  a copy  of the  GNU General  Public License
along  with  this  program;  if   not,  write  to  the  Free  Software
Foundation, Inc., 59 Temple Place  - Suite 330, Boston, MA 02111-1307,
USA.

Main Page

$Id: mqs.Call.wiki,v 1.10 2004/10/10 15:30:39 adulau Exp $