QPID-664: Initial checkin of high level messaging api for c++

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@807731 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 115 insertions, 0 deletions

diff --git a/cpp/include/qpid/messaging/Receiver.h b/cpp/include/qpid/messaging/Receiver.h
new file mode 100644
index 0000000000..e51e1093d1
--- /dev/null
+++ b/cpp/include/qpid/messaging/Receiver.h
@@ -0,0 +1,115 @@
+#ifndef QPID_MESSAGING_RECEIVER_H
+#define QPID_MESSAGING_RECEIVER_H
+
+/*
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ * 
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ */
+#include "qpid/Exception.h"
+#include "qpid/client/ClientImportExport.h"
+#include "qpid/client/Handle.h"
+#include "qpid/sys/Time.h"
+
+namespace qpid {
+namespace client {
+
+template <class> class PrivateImplRef;
+
+}
+
+namespace messaging {
+
+class Message;
+class MessageListener;
+class ReceiverImpl;
+
+/**
+ * A pull style interface for message retrieval.
+ */
+class Receiver : public qpid::client::Handle<ReceiverImpl>
+{
+  public:
+    struct NoMessageAvailable : qpid::Exception {};
+
+    QPID_CLIENT_EXTERN Receiver(ReceiverImpl* impl = 0);
+    QPID_CLIENT_EXTERN Receiver(const Receiver&);
+    QPID_CLIENT_EXTERN ~Receiver();
+    QPID_CLIENT_EXTERN Receiver& operator=(const Receiver&);
+    /**
+     * Retrieves a message from this receivers local queue, or waits
+     * for upto the specified timeout for a message to become
+     * available. Returns false if there is no message to give after
+     * waiting for the specified timeout.
+     */
+    QPID_CLIENT_EXTERN bool get(Message& message, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    /**
+     * Retrieves a message from this receivers local queue, or waits
+     * for upto the specified timeout for a message to become
+     * available. Throws NoMessageAvailable if there is no
+     * message to give after waiting for the specified timeout.
+     */
+    QPID_CLIENT_EXTERN Message get(qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    /**
+     * Retrieves a message for this receivers subscription or waits
+     * for upto the specified timeout for one to become
+     * available. Unlike get() this method will check with the server
+     * that there is no message for the subscription this receiver is
+     * serving before returning false.
+     */
+    QPID_CLIENT_EXTERN bool fetch(Message& message, qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    /**
+     * Retrieves a message for this receivers subscription or waits
+     * for upto the specified timeout for one to become
+     * available. Unlike get() this method will check with the server
+     * that there is no message for the subscription this receiver is
+     * serving before throwing an exception.
+     */
+    QPID_CLIENT_EXTERN Message fetch(qpid::sys::Duration timeout=qpid::sys::TIME_INFINITE);
+    
+    /**
+     * Enables the message flow for this receiver
+     */
+    QPID_CLIENT_EXTERN void start();
+    /**
+     * Stops the message flow for this receiver (without actually
+     * cancelling the subscription).
+     */
+    QPID_CLIENT_EXTERN void stop();
+    /**
+     * Sets the capacity for the receiver. The capacity determines how
+     * many incoming messages can be held in the receiver before being
+     * requested by a client via fetch() (or pushed to a listener).
+     */
+    QPID_CLIENT_EXTERN void setCapacity(uint32_t);
+
+    /**
+     * Cancels this receiver
+     */
+    QPID_CLIENT_EXTERN void cancel();
+
+    /**
+     * Set a message listener for receiving messages asynchronously.
+     */
+    QPID_CLIENT_EXTERN void setListener(MessageListener* listener);
+  private:
+  friend class qpid::client::PrivateImplRef<Receiver>;
+};
+}} // namespace qpid::messaging
+
+#endif  /*!QPID_MESSAGING_RECEIVER_H*/