OSCNode.h

#if IPHONE
#import <UIKit/UIKit.h>
#else
#import <Cocoa/Cocoa.h>
#endif
#import "OSCMessage.h"
#import <VVBasics/MutNRLockArray.h>
#import <VVBasics/VVBasicMacros.h>
#import <libkern/OSAtomic.h>




@protocol OSCNodeDelegateProtocol
- (void) node:(id)n receivedOSCMessage:(OSCMessage *)msg;
- (void) nodeNameChanged:(id)node;
- (void) nodeDeleted:(id)node;
@end



@protocol OSCNodeQueryDelegate
- (NSMutableArray *) namespaceArrayForNode:(id)n;
- (NSString *) docStringForNode:(id)n;
- (NSString *) typeSignatureForNode:(id)n;
- (OSCValue *) currentValueForNode:(id)n;
- (NSString *) returnTypeStringForNode:(id)n;
@end





@interface OSCNode : NSObject {
    id                  addressSpace;   //  the class OSCAddressSpace is a subclass of OSCNode, and is essentially the "root" node.  all OSCNodes have a pointer to the root node!
    BOOL                deleted;
    
    OSSpinLock          nameLock;
    NSString            *nodeName;  //  "local" name: name of the node at /a/b/c is "c"
    NSString            *fullName;  //  "full" name: name of the node at /a/b/c is "/a/b/c"
    MutLockArray        *nodeContents;  //  Contains OSCNode instances- this OSCNode's sub-nodes.  type 'MutLockArray'- this should all be threadsafe...
    OSCNode             *parentNode;    //  my "parent" node (or nil).  NOT retained!
    OSCNodeType         nodeType;   //  What 'type' of node i am
    BOOL                hiddenInMenu;   //  NO by default. if YES, this node (and all its sub-nodes) will be omitted from menus!
    
    OSCMessage          *lastReceivedMessage;   //  retained
    OSSpinLock          lastReceivedMessageLock;
    MutNRLockArray      *delegateArray; //  type 'MutNRLockArray'. contents are NOT retained! could be anything!
    
    BOOL                autoQueryReply; //  NO by default
    id <OSCNodeQueryDelegate>   queryDelegate;  //  NOT RETAINED
}

/*  only called by the address space to craft a formatted string for logging purposes   */
- (void) _logDescriptionToString:(NSMutableString *)s tabDepth:(int)d;

//  Creates and returns an auto-released instance of OSCNode with the passed name.  Returns nil if passed a nil name.
+ (id) createWithName:(NSString *)n;
//  Inits an instance of OSCNode with the passed name.  Returns nil if passed a nil name.
- (id) initWithName:(NSString *)n;
- (id) init;

- (void) prepareToBeDeleted;

- (NSComparisonResult) nodeNameCompare:(OSCNode *)comp;

//  Adds the passed node to my ndoe contents
- (void) addLocalNode:(OSCNode *)n;
//  Adds the passed nodes to my node contents
- (void) addLocalNodes:(NSArray *)n;
//  Call this to remove the passed node from my contents.  This method releases the passed node, but doesn't try to deactivate it!  If the node was only retained by the address space, this is equivalent to "deleteLocalNode:".
- (void) removeLocalNode:(OSCNode *)n;
//  Call this to remove the passed node from my contents.  This method releases the passed node and deactivates it (calls "prepareToBeDeleted" so it stops sending delegate methods/responding).
- (void) deleteLocalNode:(OSCNode *)n;
- (void) removeFromAddressSpace;

//  It's assumed that the passed name doesn't have any wildcards/regex.  If the receiver contains a node with the identical name as the passed string, the node will be returned.  This is not a "deep" search, it's restricted to the receiver's nodeContents array.
- (OSCNode *) findLocalNodeNamed:(NSString *)n;
//  Same as findLocalNodeNamed:, but if any of the interim nodes don't exist they will be created.
- (OSCNode *) findLocalNodeNamed:(NSString *)n createIfMissing:(BOOL)c;

//  Compares the names of all the receiver's sub-nodes to the passed POSIX regex string, returns an array with all the nodes whose nodeNames match the regex.  If there are no sub-nodes or none of the sub-nodes match the regex, returns nil.
- (NSMutableArray *) findLocalNodesMatchingPOSIXRegex:(NSString *)regex;
- (void) _addLocalNodesMatchingRegex:(NSString *)regex toMutArray:(NSMutableArray *)a;

//  these "findNode" methods DO NOT USE regex!  it is assumed that the passed string is NOT a regex algorithm (the language "findNode" implies a single result, precluding the use of regex)
- (OSCNode *) findNodeForAddress:(NSString *)p;
//  It's assumed that the passed address doesn't have any wildcards/regex (no checking is done).  The receiver tries to locate the node at the passed address (relative to the receiver).  If c is YES, any OSCNodes missing in the passed address are automatically created.  If they have sub-nodes, the auto-created nodes' types are set to OSCNodeDirectory; if not, the auto-created nodes' types are OSCNodeTypeUnknown
- (OSCNode *) findNodeForAddress:(NSString *)p createIfMissing:(BOOL)c;
- (OSCNode *) findNodeForAddressArray:(NSArray *)a;
- (OSCNode *) findNodeForAddressArray:(NSArray *)a createIfMissing:(BOOL)c;
//  THESE METHODS ALWAYS USE REGEX TO FIND MATCHES!  path components may be regex strings- this returns all the nodes that match every component in the passed address/address array!
- (NSMutableArray *) findNodesMatchingAddress:(NSString *)a;
- (NSMutableArray *) findNodesMatchingAddressArray:(NSArray *)a;

//  If you want to receive OSC messages and other info (OSCNodeDelegateProtocol) from an OSCNode, you need to be its delegate.
//  NODE DELEGATES ARE __NOT__ RETAINED!
//  NODE DELEGATES __MUST__ REMOVE THEMSELVES FROM THE DELEGATE ARRAY!
- (void) addDelegate:(id <OSCNodeDelegateProtocol>)d;
- (void) removeDelegate:(id)d;
- (void) informDelegatesOfNameChange;
- (void) addDelegatesFromNode:(OSCNode *)n;

- (void) dispatchMessage:(OSCMessage *)m;

- (OSCMessage *) generateAutomaticResponseForQuery:(OSCMessage *)m;

@property (assign, readwrite) id addressSpace;
@property (assign, readwrite) NSString *nodeName;
- (void) _setNodeName:(NSString *)n;
@property (readonly) NSString *fullName;
@property (readonly) MutLockArray *nodeContents;
@property (assign, readwrite) OSCNode *parentNode;
@property (assign, readwrite) OSCNodeType nodeType;
@property (assign, readwrite) BOOL hiddenInMenu;
@property (readonly) OSCMessage *lastReceivedMessage;
@property (readonly) OSCValue *lastReceivedValue;
@property (readonly) id delegateArray;
@property (assign,readwrite) BOOL autoQueryReply;
@property (assign,readwrite) id<OSCNodeQueryDelegate> queryDelegate;

@end