Permalink
Browse files

Moving a few private components out of the header file and into the i…

…mplementation file.
  • Loading branch information...
robbiehanson committed Jul 13, 2012
1 parent 0219ef6 commit 01e9cf267b86966a9c06cd8bf7aa4c16641642e2
Showing with 41 additions and 20 deletions.
  1. +5 −12 Core/XMPPInternal.h
  2. +16 −1 Core/XMPPStream.h
  3. +20 −7 Core/XMPPStream.m
View
@@ -4,18 +4,6 @@
#import "XMPPSASLAuthentication.h"
-// Define the various timeouts (in seconds) for retreiving various parts of the XML stream
-#define TIMEOUT_XMPP_WRITE -1
-#define TIMEOUT_XMPP_READ_START 10
-#define TIMEOUT_XMPP_READ_STREAM -1
-
-// Define the various tags we'll use to differentiate what it is we're currently reading or writing
-#define TAG_XMPP_READ_START 100
-#define TAG_XMPP_READ_STREAM 101
-#define TAG_XMPP_WRITE_START 200
-#define TAG_XMPP_WRITE_STREAM 201
-#define TAG_XMPP_WRITE_RECEIPT 202
-
// Define the various states we'll use to track our progress
enum XMPPStreamState
{
@@ -50,6 +38,11 @@ extern NSString *const XMPPStreamDidChangeMyJIDNotification;
@interface XMPPStream (/* Internal */)
+/**
+ * Categories on XMPPStream should maintain thread safety by dispatching through the internal xmppQueue.
+ * They may also need to ensure the stream is in the proper state for their activity.
+**/
+
@property (readonly) dispatch_queue_t xmppQueue;
@property (readonly) XMPPStreamState state;
View
@@ -771,6 +771,11 @@ typedef enum XMPPStreamErrorCode XMPPStreamErrorCode;
* In the case of an IQ, the delegate method should return YES if it has or will respond to the given IQ.
* If the IQ is of type 'get' or 'set', and no delegates respond to the IQ,
* then xmpp stream will automatically send an error response.
+ *
+ * Concerning thread-safety, delegates shouldn't modify the given elements.
+ * As documented in NSXML / KissXML, elements are read-access thread-safe, but write-access thread-unsafe.
+ * If you have need to modify an element for any reason,
+ * you should copy the element first, and then modify and use the copy.
**/
- (BOOL)xmppStream:(XMPPStream *)sender didReceiveIQ:(XMPPIQ *)iq;
- (void)xmppStream:(XMPPStream *)sender didReceiveMessage:(XMPPMessage *)message;
@@ -789,14 +794,24 @@ typedef enum XMPPStreamErrorCode XMPPStreamErrorCode;
/**
* These methods are called before their respective XML elements are sent over the stream.
- * These methods can be used to customize elements on the fly.
+ * These methods can be used to modify outgoing elements on the fly.
* (E.g. add standard information for custom protocols.)
*
* You may also filter outgoing elements by returning nil.
*
* When implementing these methods to modify the element, you do not need to copy the given element.
* You can simply edit the given element, and return it.
* The reason these methods return an element, instead of void, is to allow filtering.
+ *
+ * Concerning thread-safety, delegates implementing the method are invoked one-at-a-time to
+ * allow thread-safe modification of the given elements.
+ *
+ * You should NOT implement these methods unless you have good reason to do so.
+ * For general processing and notification of sent elements, please use xmppStream:didSendX: methods.
+ *
+ * @see xmppStream:didSendIQ:
+ * @see xmppStream:didSendMessage:
+ * @see xmppStream:didSendPresence:
**/
- (XMPPIQ *)xmppStream:(XMPPStream *)sender willSendIQ:(XMPPIQ *)iq;
- (XMPPMessage *)xmppStream:(XMPPStream *)sender willSendMessage:(XMPPMessage *)message;
View
@@ -63,6 +63,17 @@
**/
#define return_from_block return
+// Define the timeouts (in seconds) for retreiving various parts of the XML stream
+#define TIMEOUT_XMPP_WRITE -1
+#define TIMEOUT_XMPP_READ_START 10
+#define TIMEOUT_XMPP_READ_STREAM -1
+
+// Define the tags we'll use to differentiate what it is we're currently reading or writing
+#define TAG_XMPP_READ_START 100
+#define TAG_XMPP_READ_STREAM 101
+#define TAG_XMPP_WRITE_START 200
+#define TAG_XMPP_WRITE_STREAM 201
+#define TAG_XMPP_WRITE_RECEIPT 202
NSString *const XMPPStreamErrorDomain = @"XMPPStreamErrorDomain";
NSString *const XMPPStreamDidChangeMyJIDNotification = @"XMPPStreamDidChangeMyJID";
@@ -1822,7 +1833,7 @@ - (void)sendIQ:(XMPPIQ *)iq withTag:(long)tag
NSAssert(state == STATE_XMPP_CONNECTED, @"Invoked with incorrect state");
// We're getting ready to send an IQ.
- // We need to notify delegates of this action to allow them to optionally alter the IQ element.
+ // Notify delegates to allow them to optionally alter/filter the outgoing IQ.
SEL selector = @selector(xmppStream:willSendIQ:);
@@ -1836,7 +1847,7 @@ - (void)sendIQ:(XMPPIQ *)iq withTag:(long)tag
else
{
// Notify all interested delegates.
- // This must be done serially to allow them to alter the element.
+ // This must be done serially to allow them to alter the element in a thread-safe manner.
GCDMulticastDelegateEnumerator *delegateEnumerator = [multicastDelegate delegateEnumerator];
@@ -1892,7 +1903,7 @@ - (void)sendMessage:(XMPPMessage *)message withTag:(long)tag
NSAssert(state == STATE_XMPP_CONNECTED, @"Invoked with incorrect state");
// We're getting ready to send a message.
- // We need to notify delegates of this action to allow them to optionally alter the message element.
+ // Notify delegates to allow them to optionally alter/filter the outgoing message.
SEL selector = @selector(xmppStream:willSendMessage:);
@@ -1906,7 +1917,7 @@ - (void)sendMessage:(XMPPMessage *)message withTag:(long)tag
else
{
// Notify all interested delegates.
- // This must be done serially to allow them to alter the element.
+ // This must be done serially to allow them to alter the element in a thread-safe manner.
GCDMulticastDelegateEnumerator *delegateEnumerator = [multicastDelegate delegateEnumerator];
@@ -1962,7 +1973,7 @@ - (void)sendPresence:(XMPPPresence *)presence withTag:(long)tag
NSAssert(state == STATE_XMPP_CONNECTED, @"Invoked with incorrect state");
// We're getting ready to send a presence element.
- // We need to notify delegates of this action to allow them to optionally alter the presence element.
+ // Notify delegates to allow them to optionally alter/filter the outgoing presence.
SEL selector = @selector(xmppStream:willSendPresence:);
@@ -2200,7 +2211,7 @@ - (void)sendElement:(NSXMLElement *)element andGetReceipt:(XMPPElementReceipt **
if (state == STATE_XMPP_CONNECTED)
{
- receipt = [[XMPPElementReceipt alloc] init]; // autoreleased below
+ receipt = [[XMPPElementReceipt alloc] init];
[receipts addObject:receipt];
[self sendElement:element withTag:TAG_XMPP_WRITE_RECEIPT];
@@ -2237,7 +2248,9 @@ - (void)resendMyPresence
}
/**
- *
+ * This method is for use by xmpp authentication mechanism classes.
+ * They should send elements using this method instead of the public sendElement classes,
+ * as those methods don't send the elements while authentication is in progress.
**/
- (void)sendAuthElement:(NSXMLElement *)element
{

0 comments on commit 01e9cf2

Please sign in to comment.