Source/MessageQueue.h

   1 /*
   2  * MacGDBp
   3  * Copyright (c) 2013, Blue Static <http://www.bluestatic.org>
   4  *
   5  * This program is free software; you can redistribute it and/or modify it under the terms of the GNU
   6  * General Public License as published by the Free Software Foundation; either version 2 of the
   7  * License, or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
  10  * even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along with this program; if not,
  14  * write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  15  */
  16
  17 #import <Foundation/Foundation.h>
  18
  19 #import "BSProtocolThreadInvoker.h"
  20
  21 @protocol MessageQueueDelegate;
  22
  23 // MessageQueue operates a listening socket, that is connected to another
  24 // program with which it exchanges UTF8 string messages. A message contains two
  25 // parts, both terminated by '\0'. The first is an ASCII integer number that is
  26 // the length of the second part. The second part is the actual string message.
  27 @interface MessageQueue : NSObject {
  28  @private
  29   // The port number on which to open a listening socket.
  30   NSUInteger _port;
  31
  32   // The thread and its run loop on which this class primarily operates.
  33   NSThread* _thread;
  34   NSRunLoop* _runLoop;
  35
  36   // Whether or not the run loop should quit.
  37   BOOL _shouldQuit;
  38
  39   // Whether or not the message queue is connected to a client.
  40   BOOL _connected;
  41
  42   // A queue of messages that are waiting to be sent.
  43   NSMutableArray* _queue;
  44
  45   // The delegate for this class.
  46   BSProtocolThreadInvoker<MessageQueueDelegate>* _delegate;
  47
  48   // The socket that listens for new incoming connections.
  49   CFSocketRef _socket;
  50
  51   // The child socket that has been accepted from |_socket|.
  52   CFSocketNativeHandle _child;
  53
  54   // The read and write streams that are created on the |_child| socket.
  55   CFReadStreamRef _readStream;
  56   CFWriteStreamRef _writeStream;
  57
  58   // When a message is being read, this temporary buffer is used to build up
  59   // the complete message from successive reads.
  60   NSMutableString* _message;
  61   NSUInteger _totalMessageSize;
  62   NSUInteger _messageSize;
  63 }
  64
  65 // Creates a new MessasgeQueue that will listen on |port| and report information
  66 // to its |delegate|.
  67 - (id)initWithPort:(NSUInteger)port delegate:(id<MessageQueueDelegate>)delegate;
  68
  69 // Whether or not the message queue has attached itself to a child.
  70 - (BOOL)isConnected;
  71
  72 // Opens a socket that will listen for connections.
  73 - (void)connect;
  74
  75 // Closes either the listening or child socket and completely disconnects.
  76 - (void)disconnect;
  77
  78 // Enqueues a |message| to be sent to the client. This may be called from any
  79 // thread.
  80 - (void)sendMessage:(NSString*)message;
  81
  82 @end
  83
  84 // Delegate ////////////////////////////////////////////////////////////////////
  85
  86 // The delegate for the message queue. These methods are called from the thread
  87 // on which the MessageQueue was initialized.
  88 @protocol MessageQueueDelegate <NSObject>
  89 // Callback for any errors that the MessageQueue encounters.
  90 - (void)messageQueue:(MessageQueue*)queue error:(NSError*)error;
  91
  92 // Called when the listening socket has accepted a child socket.
  93 - (void)messageQueueDidConnect:(MessageQueue*)queue;
  94
  95 // Called when the child socket has been disconnected.
  96 - (void)messageQueueDidDisconnect:(MessageQueue*)queue;
  97
  98 // Callback for when a message has been sent.
  99 - (void)messageQueue:(MessageQueue*)queue didSendMessage:(NSString*)message;
 100
 101 // Callback with the message content when one has been receieved.
 102 - (void)messageQueue:(MessageQueue*)queue didReceiveMessage:(NSString*)message;
 103 @end