summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKevin Smith <git@kismith.co.uk>2012-01-25 10:14:56 (GMT)
committerKevin Smith <git@kismith.co.uk>2012-02-14 09:11:27 (GMT)
commit67087f4374ddca69c4d3d9303e85795f060f50a2 (patch)
tree2c03d3c6d77da865c536154256f4f3aba2f33f47
parente14208b0c3ced126400d6fd031a8d9a92da798c2 (diff)
downloadswift-contrib-67087f4374ddca69c4d3d9303e85795f060f50a2.zip
swift-contrib-67087f4374ddca69c4d3d9303e85795f060f50a2.tar.bz2
Adding documentation to GenericRequest
-rw-r--r--Swiften/Queries/GenericRequest.h30
1 files changed, 30 insertions, 0 deletions
diff --git a/Swiften/Queries/GenericRequest.h b/Swiften/Queries/GenericRequest.h
index 9fd934f..b9cc6fc 100644
--- a/Swiften/Queries/GenericRequest.h
+++ b/Swiften/Queries/GenericRequest.h
@@ -11,9 +11,25 @@
#include <Swiften/Queries/Request.h>
namespace Swift {
+ /**
+ * GenericRequest is used for managing the sending of, and handling of replies to, iq stanzas that do not have their own Request types.
+ *
+ * To create an iq stanza, call a constructor with the type of the iq that needs to be sent (either Set or Get), addressing information (clients should use the constructor that doesn't specify a sender), the payload that should be sent in the iq, and the IQRouter for the connection, obtained through the Client or CoreClient object.
+ *
+ * Having created a GenericRequest, connect to the onResponse signal to be told when a response (either a result or an error) has been received by Swiften.
+ *
+ * To send the iq, then call send() - onResponse will be called when a reply is received.
+ */
template<typename PAYLOAD_TYPE>
class GenericRequest : public Request {
public:
+ /**
+ * Create a request suitable for client use.
+ * @param type Iq type - Get or Set.
+ * @param receiver JID to send request to.
+ * @param payload Payload to send in stanza.
+ * @param router IQRouter instance for current connection.
+ */
GenericRequest(
IQ::Type type,
const JID& receiver,
@@ -22,6 +38,14 @@ namespace Swift {
Request(type, receiver, payload, router) {
}
+ /**
+ * Create a request suitable for component or server use. As a client, use the other constructor instead.
+ * @param type Iq type - Get or Set.
+ * @param sender JID to use in "from" of stanza.
+ * @param receiver JID to send request to.
+ * @param payload Payload to send in stanza.
+ * @param router IQRouter instance for current connection.
+ */
GenericRequest(
IQ::Type type,
const JID& sender,
@@ -31,6 +55,9 @@ namespace Swift {
Request(type, sender, receiver, payload, router) {
}
+ /**
+ * Internal method, do not use.
+ */
virtual void handleResponse(boost::shared_ptr<Payload> payload, ErrorPayload::ref error) {
onResponse(boost::dynamic_pointer_cast<PAYLOAD_TYPE>(payload), error);
}
@@ -41,6 +68,9 @@ namespace Swift {
}
public:
+ /**
+ * Signal emitted when a reply to the iq has been received. Contains a payload if one was present, and an error if one was present.
+ */
boost::signal<void (boost::shared_ptr<PAYLOAD_TYPE>, ErrorPayload::ref)> onResponse;
};
}