AmbientC Class Reference

#import <AmbientC.h>

Collaboration diagram for AmbientC:

List of all members.

Public Member Functions

(BOOL) - exportService:

Export a service and make it available for discovery by other devices running Ambient-C and receiving of messages.

(BOOL) - exportClass:asServiceType:

(BOOL) - removeService:

Remove an already exported service.

(void) - setDebugInfo:

Method for logging information to NSLog.

(id) - delegate

(void) - setDelegate:

Method to set delegate to receive events from the framework.

(BOOL) - setupBonjourBrowserAndSocket:onPort:

Internal. Method used for setting up the Bonjour service and socket functionality on a specified port number.

(BOOL) - setupBonjourPublish:withServiceType:onPort:

Internal. Method used for setting up the Bonjour publishing of o a service.

(BOOL) - sendDataToSocket:withData:

(BOOL) - sendEncodedMessageToSocket:withMessage:

(NSArray *) - trimNullAddresses:

Internal. Method used for removing null IP addresses from an array.

(BOOL) - invokeRemoteMethodOnServices:withInvocation:withArgument:

(BOOL) - invokeRemoteMethodOnServices:withSelector:onClass:withArgument:

(BOOL) - sendMessageToAllConnectedServices:

Send message to all connected services within Ambient-C identifier.

(BOOL) - sendMessageToServices:ofServiceType:

Send message to all connected services of a specified service type within Ambient-C identifier.

(BOOL) - sendMessageToService:ofServiceId:

Send message to a specific service, identified by unique service ID, within Ambient-C identifier.

(void) - netServiceWillPublish:

(void) - netService:didNotPublish:

(void) - netServiceDidStop:

(void) - netServiceDidPublish:

(void) - netServiceBrowser:didFindService:moreComing:

(void) - netServiceBrowser:didRemoveService:moreComing:

(void) - netService:didNotResolve:

(void) - netServiceDidResolveAddress:

(void) - netsocket:connectionAccepted:

(void) - netsocket:dataAvailable:

(void) - netsocketDisconnected:

(id) - init [implementation]

(void) - dealloc [implementation]

Static Public Member Functions

(AmbientC *) + ambientC

(AmbientC *) + ambientCDiscoverServicesWithIdentifier:

Setup Ambient-C for only discovering with specified identifier.

(AmbientC *) + ambientCExportServiceWithIdentifier:withServiceType:

Setup Ambient-C and only export one service with a specified servicetype.

(AmbientC *) + ambientCExportDiscoverServicesWithIdentifier:withServiceType:

Setup Ambient-C for discovery within a specified identifier and export one service at the same type.

(AmbientC *) + ambientCExportDiscoverServicesWithIdentifier:withServiceType:onPort:

Setup Ambient-C for discovery within a specified identifier and export one service at the same type on a specified port.

Protected Attributes

NSMutableArray * foundBonjourServicesArray

NSMutableArray * incomingSocketArray

NSMutableArray * outgoingSocketArray

NSMutableArray * serviceListArray

NSMutableArray * publishServiceArray

NSMutableArray * tempServicePointerArray

NSNetServiceBrowser * discoverBonjourService

NetSocket * listenSocket

NetSocket * socketToRemoteHost

id bDelegate

BOOL debugMode

int defaultPort

Properties

NSString * ACIdentifier

Detailed Description

Ambient-Oriented framework for iPod Touch and iPhone

Definition at line 109 of file AmbientC.h.

Member Function Documentation

+ (AmbientC *) ambientC

Internal class method which returns an Ambient-C object

Returns:: Ambient-C object

Definition at line 72 of file AmbientC.m.

Here is the caller graph for this function:

+ (AmbientC *) ambientCDiscoverServicesWithIdentifier: (NSString *) aCIdentifier

Setup Ambient-C for only discovering with specified identifier.

Method for only discovering services within the identifier.

Parameters:

aCIdentifier

The identifier for Ambient-C. Only discover services with this identifier.

Returns:: Ambient-C object initialized for discovery with specified identifier, nil if creation was unsuccesfull due to an error.

Definition at line 88 of file AmbientC.m.

Here is the call graph for this function:

+ (AmbientC *) ambientCExportDiscoverServicesWithIdentifier:	(NSString *)	aCIdentifier
withServiceType:	(NSString *)	serviceType

Setup Ambient-C for discovery within a specified identifier and export one service at the same type.

Method for setting up Ambient-C with basic discovery service exporting and discovery. This is probably the method you need if you want to do basic setup.

Parameters:

	aCIdentifier	The identifier for Ambient-C. Only discover services with this identifier. E.g. "piano".
	serviceType	Supply an `NSString` object with the service you would like to export. E.g. "speaker".

Returns:: Ambient-C object initialized for discovery with specified identifier, nil if creation was unsuccesfull due to an error.

Definition at line 116 of file AmbientC.m.

Here is the call graph for this function:

Here is the caller graph for this function:

+ (AmbientC *) ambientCExportDiscoverServicesWithIdentifier:	(NSString *)	aCIdentifier
withServiceType:	(NSString *)	serviceType
onPort:	(UInt16)	port

Setup Ambient-C for discovery within a specified identifier and export one service at the same type on a specified port.

Method for setting up Ambient-C with basic discovery service exporting and discovery on a different port number than default (60700).

Parameters:

	aCIdentifier	The identifier for AmbientC. Only discover services with this identifier. E.g. "piano".
	serviceType	Supply an `NSString` object with the service you would like to export. E.g. "speaker".
	port	Specifies the port number to be used for socket communication. Make sure a free socket port is chosen. See also Wikipedia - List of TCP and UDP Port Numbers. Also note that it is good behaviour to choose the same port number for all devices / services, untested with port numbers different for each device / service.

Returns:: Ambient-C object initialized for discovery with specified identifier, nil if creation was unsuccesfull due to an error.

Definition at line 132 of file AmbientC.m.

Here is the call graph for this function:

+ (AmbientC *) ambientCExportServiceWithIdentifier:	(NSString *)	aCIdentifier
withServiceType:	(NSString *)	serviceType

Setup Ambient-C and only export one service with a specified servicetype.

Method for setting up Ambient-C with only exporting a service. Use this method if service discovery is not needed and the extra load of service discovery is not wanted.

Parameters:

	aCIdentifier	The identifier for Ambient-C. This identifier is necessary for devices that want to discover this service.
	serviceType	Supply an `NSString` object with the service you would like to export

Returns:: Ambient-C object initialized with specified identifier, nil if creation was unsuccesfull due to an error.

Definition at line 102 of file AmbientC.m.

Here is the call graph for this function:

- (void) dealloc [implementation]

Definition at line 47 of file AmbientC.m.

- (id) delegate

Internal. Returns the delegate.

Returns:: Delegate for Ambient-C

Definition at line 145 of file AmbientC.m.

- (BOOL) exportClass:	(id *)	pointerToClass
asServiceType:	(NSString *)	serviceType

Definition at line 207 of file AmbientC.m.

Here is the call graph for this function:

- (BOOL) exportService: (NSString *) serviceType

Export a service and make it available for discovery by other devices running Ambient-C and receiving of messages.

Method for exporting a service after AmbientC has been started. This service will be exported for the AmbientC identifier as specified in the object created. E.g.

aC = [[AmbientC ambientCDiscoverServicesWithIdentifier:@"iPiano"] retain];
//...
[aC exportService:@"speaker"];

This above code sample will first only discover services within "iPiano" (first line). When the third line is executed, the service will be exported for that identifier, making it available for discovery for other devices within the AmbientCIdentifier. Messages for that service will be received through the delegate after that time.

Parameters:

serviceType An NSString object with the name of the service to be exported.

Returns:: BOOL object determining succes of exporting. Returns NO if failure occurred while creating service, YES in all other cases.

Remarks:: Only returns NO when failure occurred in creating service. Returns YES if the service was created successfully or if the service already exists (in which case nothing happened).

Definition at line 185 of file AmbientC.m.

Here is the caller graph for this function:

- (id) init [implementation]

Definition at line 26 of file AmbientC.m.

- (BOOL) invokeRemoteMethodOnServices:	(NSString *)	servType
withInvocation:	(NSInvocation *)	invocation
withArgument:	(id)	arg

Definition at line 595 of file AmbientC.m.

- (BOOL) invokeRemoteMethodOnServices:	(NSString *)	servType
withSelector:	(SEL)	selector
onClass:	(id *)	class
withArgument:	(NSString *)	arg

Definition at line 634 of file AmbientC.m.

- (void) netService:	(NSNetService *)	netService
didNotPublish:	(NSDictionary *)	errorDict

Internal method for delegate of NSNetservice, only for debugging. Publishing of a NSNetService failed.

Definition at line 388 of file AmbientC.m.

- (void) netService:	(NSNetService *)	sender
didNotResolve:	(NSDictionary *)	errorDict

Internal method for delegate of NSNetServiceBrowser, informing that resolving a service failed.
Failure could be because of a network or timeout error, reason will be displayed if the debugging mode is set to YES. Removing unresolved NSNetService object from array with found services.

Definition at line 474 of file AmbientC.m.

- (void) netServiceBrowser:	(NSNetServiceBrowser *)	browser
didFindService:	(NSNetService *)	aNetService
moreComing:	(BOOL)	moreComing

Internal method for delegate of NSNetserviceBrowser, informing that NSNetServiceBrowser discovered a service within the Ambient-C identifier. This method performs important actions when a service has been discovered:

Check for a compatible Bonjour name, ignore if incompatible
If the name is compatible, perform a check whether we found a local exported service. Ignore if local
If service is remote, start resolve with a 5-second timeout.

Definition at line 422 of file AmbientC.m.

- (void) netServiceBrowser:	(NSNetServiceBrowser *)	browser
didRemoveService:	(NSNetService *)	aNetService
moreComing:	(BOOL)	moreComing

Internal method for delegate of NSNetServiceBrowser, informing that a service has disappeared.
This method performs important actions for detecting service / device disconnections. Scheme:

Make copy of the main array (grouping the pointers to all objects together) for supporting mutation during fast enumeration.
Check if the service which which was removed appears in the main array.
If that is the case, inform with a delegate (respondsToSelector ) about the removal

Definition at line 447 of file AmbientC.m.

- (void) netServiceDidPublish: (NSNetService *) sender

Internal method for delegate of NSNetservice, only for debugging. A NSNetService published succesfully. Should be called each time after exporting a service.

Definition at line 408 of file AmbientC.m.

- (void) netServiceDidResolveAddress: (NSNetService *) aNetService

Internal method for delegate of NSNetServiceBrowser, informing about success of service resolution.
This method is the most important of Ambient-C. In this method the main array is built, containing pointers to relevant sockets, IP addresses, etc.
Following is a description of the algorithm of this method:

Get the not-null addresses of the resolved NSNetService object. If there are no not-null addresses, log this and ignore service.
If there are valid IP addresses, then perform the check wether the Bonjour naming is correct (see also the delegate didFindService). If not correct, log this and ignore service.
If the naming was correct, open a socket to this resolved service on the IP address and port number as we get from the resolved service.
Create a NSDictionary object containing keys: uniqueserviceid (the name of the service is a unique identifier for every single service discovered in the group), outsocketpointer (the pointer to the outsocket created in previous step, necessary for when a service disconnectedd or data was received), foundbonjourservicepointer (the pointer to the corresponding NSNetService object representing the service), devicename (name of the device, e.g. 'Tim's iPod'), servicename (name of discovered service e.g. 'speaker'), ipaddress (the IP address used to connect the socket) and the port number.
Add this NSDictionary object to serviceListArray, the main array for Ambient-C and log this.
Perform a selector on serviceDiscovered with serviceName, deviceName, uniqueserviceid. This is the delegate for AmbientC.

Definition at line 491 of file AmbientC.m.

Here is the call graph for this function:

- (void) netServiceDidStop: (NSNetService *) netService

Internal method for delegate of NSNetservice, only for debugging. A NSNetService stopped. This is normal behaviour after calling a 'stop' on a NSNetService, or after resolving a NSNetService object.

Definition at line 398 of file AmbientC.m.

- (void) netServiceWillPublish: (NSNetService *) netService

Internal method for delegate of NSNetservice, only for debugging. Publishing of a NSNetService will happen.

Definition at line 378 of file AmbientC.m.

- (void) netsocket:	(NetSocket*)	inNetSocket
connectionAccepted:	(NetSocket*)	inNewNetSocket

Internal method for delegate of NetSocket, gets called every time a connection is accepted.
This method accepts every socket connection to this device and adds it to the array of incoming socket connections.

Definition at line 537 of file AmbientC.m.

Here is the call graph for this function:

- (void) netsocket:	(NetSocket*)	inNetSocket
dataAvailable:	(unsigned)	inAmount

Internal method for delegate of NetSocket, called every time data is available.
This method is one of the most important methods in Ambient-C, because it is this one that is responsible for receiving messages. Retrieves the data received from the socket, encodes it back to UTF8, looks up the details for the originating service and calls the delegate with the appropriate values.

Definition at line 552 of file AmbientC.m.

Here is the call graph for this function:

- (void) netsocketDisconnected: (NetSocket*) inNetSocket

Internal method for delegate of NetSocket, called every time a socket is disconnected.
Removes the disconnected sockets from the array to clear memory, but service disconnections are handled by the delegate of NSNetservice

Definition at line 569 of file AmbientC.m.

- (BOOL) removeService: (NSString *) serviceType

Remove an already exported service.

Method for removing an exported service from AmbientC. This can be any method which was exported previously or the method exported with the setup method for Ambient-C. Once this service has been removed, messages for this service won't be received anymore.

Parameters:

serviceType An NSString object with the name of the service to be removed from exported services.

Returns:: BOOL object determining succes of removal. Returns YES if removal succeeded, NO if an occurred while removing the service (e.g. service not found).

Definition at line 219 of file AmbientC.m.

Here is the caller graph for this function:

- (BOOL) sendDataToSocket:	(NetSocket *)	socketToSendTo
withData:	(NSData *)	dataToSend

Internal. Method used to send NSData object to a socket.

Parameters:

	socketToSendTo	Reference to `NetSocket` object where the data should be sent to.
	dataToSend	`NSData` object containing the data to be send to the socket.

Returns:: Returns a BOOL value whether the socket was online or not.

Definition at line 326 of file AmbientC.m.

Here is the call graph for this function:

- (BOOL) sendEncodedMessageToSocket:	(NetSocket *)	socketToSendTo
withMessage:	(NSString *)	messageToSend

Internal. Method used to send a message to a socket, with standard encoding, NSUTF8StringEncoding.

Parameters:

	socketToSendTo	Reference to `NetSocket` object where the data should be sent to.
	messageToSend	The message to send to the specified socket.

Returns:: Returns a BOOL value whether the socket was online or not.

Definition at line 341 of file AmbientC.m.

Here is the call graph for this function:

Here is the caller graph for this function:

- (BOOL) sendMessageToAllConnectedServices: (NSString*) messageToSend

Send message to all connected services within Ambient-C identifier.

Sending a message to all services found within the Ambient-C identifier.

Parameters:

messageToSend

The message to be sent to all services within the Ambient-C identifier.

Returns:: Returns YES if sending succeeded for all services, NO if failed for one or more services.

Definition at line 646 of file AmbientC.m.

Here is the call graph for this function:

- (BOOL) sendMessageToService:	(NSString *)	messageToSend
ofServiceId:	(NSString *)	serviceId

Send message to a specific service, identified by unique service ID, within Ambient-C identifier.

Sending a message to a specific service.

Parameters:

	messageToSend	The message to be sent to the specified service.
	serviceId	The unique identifier of the service where the message should ben sent to.

Returns:: Returns YES if sending succeeded, NO if failed.

Definition at line 689 of file AmbientC.m.

Here is the call graph for this function:

- (BOOL) sendMessageToServices:	(NSString *)	messageToSend
ofServiceType:	(NSString *)	servType

Send message to all connected services of a specified service type within Ambient-C identifier.

Sending a message to a specific type of services. All devices running this service in the specified Ambient-C identifier will receive this message.

Parameters:

	messageToSend	The message to be sent to the specified type of service.
	servType	The type of services where the message has to be send to.

Returns:: Returns YES if sending to all services succeeded, NO if one or more failed.

Definition at line 662 of file AmbientC.m.

- (void) setDebugInfo: (BOOL) outputDebugInfo

Method for logging information to NSLog.

Sets the debugging to NSLog on or off. Provides useful information while debuggin about service discovery, service disconnections and data / messages received.

Parameters:

outputDebugInfo BOOL value setting the debugging information

Definition at line 166 of file AmbientC.m.

Here is the caller graph for this function:

- (void) setDelegate: (id) inDelegate

Method to set delegate to receive events from the framework.

Internal. Sets the delegate to a specified delegate.

Parameters:

inDelegate

Delegate object

Definition at line 155 of file AmbientC.m.

Here is the caller graph for this function:

- (BOOL) setupBonjourBrowserAndSocket:	(NSString *)	aCIdentifier
onPort:	(UInt16)	port

Internal. Method used for setting up the Bonjour service and socket functionality on a specified port number.

This method basically does three things:

Set up the Ambient-C Identifier. Raises NSException in case no identifier was supplied.
Sets up NSNetServiceBrowser for discovery of services with the ACIdentifier, returns NO if that failed.
Sets up the listensocket on the specified port number (default: 60700 or specified). If these three items succeeded, then YES is returned. This BOOL value is used in higher methods to determine whether Ambient-C can be created.

Parameters:

	aCIdentifier	The name of the cloud in which the services will be detected. Supplied by higher (externally available) methods.
	port	Receives the port number to be used for the publishing with Bonjour and setting the sockets ports. Required.

Returns:: Returns a BOOL value whether all setup went okay. If something failed, this will result in NO, propagating through higher methods.

Definition at line 248 of file AmbientC.m.

Here is the call graph for this function:

- (BOOL) setupBonjourPublish:	(NSString *)	aCIdentifier
withServiceType:	(NSString *)	serviceType
onPort:	(UInt16)	port

Internal. Method used for setting up the Bonjour publishing of o a service.

This method performs two operations:

Setting up NSNetService for service exporting (publishing) with the special form of ACIdentifier, returns NO if that failed.
Adds the published NSNetService to the array of published services

Parameters:

	aCIdentifier	The name of the cloud in which the services will be detected. Supplied by higher (externally available) methods.
	serviceType	Name of the service to be exported. E.g. "speaker".
	port	Receives the port number to be used for the publishing with Bonjour and setting the sockets ports. Required.

Returns:: Returns a BOOL value whether all setup went okay. If something failed, this will result in NO, propagating through higher methods.

Definition at line 292 of file AmbientC.m.

- (NSArray *) trimNullAddresses: (NSArray *) addresses

Internal. Method used for removing null IP addresses from an array.

Internal method performing an NSArray operation. Loops over all NSData objects in the array, checking whether the IP address is not null. This method is used for a resolved NSNetService object when the addresses are retrieved. Sometimes an IP address of the form "0.0.0.0" appears. This address is not wanted and removed from the array.

Remarks:: This method is using the extension on NSData, NSDataSocketInformation.

Parameters:

addresses An NSArray containing NSData objects (mostly obtained from a resolved NSNetService instance) containing IP addresses and port numbers.

Returns:: Returns the array with the null addresses removed.

Definition at line 361 of file AmbientC.m.

Here is the caller graph for this function:

Member Data Documentation

- (id) bDelegate [protected]

Definition at line 114 of file AmbientC.h.

- (BOOL) debugMode [protected]

Definition at line 116 of file AmbientC.h.

- (int) defaultPort [protected]

Definition at line 117 of file AmbientC.h.

- (NSNetServiceBrowser*) discoverBonjourService [protected]

Definition at line 112 of file AmbientC.h.

- (NSMutableArray*) foundBonjourServicesArray [protected]

Definition at line 110 of file AmbientC.h.

- (NSMutableArray *) incomingSocketArray [protected]

Definition at line 110 of file AmbientC.h.

- (NetSocket*) listenSocket [protected]

Definition at line 113 of file AmbientC.h.

- (NSMutableArray *) outgoingSocketArray [protected]

Definition at line 110 of file AmbientC.h.

- (NSMutableArray *) publishServiceArray [protected]

Definition at line 110 of file AmbientC.h.

- (NSMutableArray *) serviceListArray [protected]

Definition at line 110 of file AmbientC.h.

- (NetSocket *) socketToRemoteHost [protected]

Definition at line 113 of file AmbientC.h.

- (NSMutableArray*) tempServicePointerArray [protected]

Definition at line 111 of file AmbientC.h.

Property Documentation

- (NSString *) ACIdentifier [read, retain]

Definition at line 115 of file AmbientC.h.

The documentation for this class was generated from the following files:

/Users/timkerger/Documents/School/VUB/Project/Subversioned/iPiano 2/Classes/AmbientC.h
/Users/timkerger/Documents/School/VUB/Project/Subversioned/iPiano 2/Classes/AmbientC.m


Public Member Functions
(BOOL)	- exportService:
	Export a service and make it available for discovery by other devices running Ambient-C and receiving of messages.
(BOOL)	- exportClass:asServiceType:
(BOOL)	- removeService:
	Remove an already exported service.
(void)	- setDebugInfo:
	Method for logging information to `NSLog`.
(id)	- delegate
(void)	- setDelegate:
	Method to set delegate to receive events from the framework.
(BOOL)	- setupBonjourBrowserAndSocket:onPort:
	Internal. Method used for setting up the Bonjour service and socket functionality on a specified port number.
(BOOL)	- setupBonjourPublish:withServiceType:onPort:
	Internal. Method used for setting up the Bonjour publishing of o a service.
(BOOL)	- sendDataToSocket:withData:
(BOOL)	- sendEncodedMessageToSocket:withMessage:
(NSArray *)	- trimNullAddresses:
	Internal. Method used for removing `null` IP addresses from an array.
(BOOL)	- invokeRemoteMethodOnServices:withInvocation:withArgument:
(BOOL)	- invokeRemoteMethodOnServices:withSelector:onClass:withArgument:
(BOOL)	- sendMessageToAllConnectedServices:
	Send message to all connected services within Ambient-C identifier.
(BOOL)	- sendMessageToServices:ofServiceType:
	Send message to all connected services of a specified service type within Ambient-C identifier.
(BOOL)	- sendMessageToService:ofServiceId:
	Send message to a specific service, identified by unique service ID, within Ambient-C identifier.
(void)	- netServiceWillPublish:
(void)	- netService:didNotPublish:
(void)	- netServiceDidStop:
(void)	- netServiceDidPublish:
(void)	- netServiceBrowser:didFindService:moreComing:
(void)	- netServiceBrowser:didRemoveService:moreComing:
(void)	- netService:didNotResolve:
(void)	- netServiceDidResolveAddress:
(void)	- netsocket:connectionAccepted:
(void)	- netsocket:dataAvailable:
(void)	- netsocketDisconnected:
(id)	- init `[implementation]`
(void)	- dealloc `[implementation]`
Static Public Member Functions
(AmbientC *)	+ ambientC
(AmbientC *)	+ ambientCDiscoverServicesWithIdentifier:
	Setup Ambient-C for only discovering with specified identifier.
(AmbientC *)	+ ambientCExportServiceWithIdentifier:withServiceType:
	Setup Ambient-C and only export one service with a specified servicetype.
(AmbientC *)	+ ambientCExportDiscoverServicesWithIdentifier:withServiceType:
	Setup Ambient-C for discovery within a specified identifier and export one service at the same type.
(AmbientC *)	+ ambientCExportDiscoverServicesWithIdentifier:withServiceType:onPort:
	Setup Ambient-C for discovery within a specified identifier and export one service at the same type on a specified port.
Protected Attributes
NSMutableArray *	foundBonjourServicesArray
NSMutableArray *	incomingSocketArray
NSMutableArray *	outgoingSocketArray
NSMutableArray *	serviceListArray
NSMutableArray *	publishServiceArray
NSMutableArray *	tempServicePointerArray
NSNetServiceBrowser *	discoverBonjourService
NetSocket *	listenSocket
NetSocket *	socketToRemoteHost
id	bDelegate
BOOL	debugMode
int	defaultPort
Properties
NSString *	ACIdentifier