NetReceive


Overview


NetReceive is a Cocoa class which simplifies the use of the Core Audio's AUNetReceive Audio Unit.

NetReceive does not use any specific port number. Instead, it uses the client supplied Bonjour service name of the AUNetSend component. This is the same Bonjour name that you see when you create an AUNetSend effects in the AULab, as seen below:

The AUNetReceive user interface (not used by NetReceive)

When NetReceive is paired with NetSend in the NetAudio framework, this Bonjour service name is the same name that you'd set in the NetSend's setServiceName: method.

NetReceive calls Bonjour services to resolve the IP address and port number of the AUNetSend service (_apple-ausend._tcp.). It will therefore find the AUNetSend service that is on the local network, not just on the local computer.

When the IP address and port number are resolved by Bonjour services, NetReceive will call the delegate's netReceive:addressChanged:port method. If connection to a AUNetSend stream is lost, NetReceive will call the delegate's netReceive:disconnectedFromAddress:port method.

Instead of using Bonjour to resolve a service name, NetReceive can also be initialized to directly use a fixed IP address and port number without going though Bonjour by using the initWithAddress:port:delegate:samplesPerBuffer method, or by using the setAddress:port: method. For consistency, both of these methods will also call the delegate's netReceive:addressChanged:port method.

In the simplest usage, you would allocate and initialize NetReceive and send it a startSampling message when you want to receive an audio stream. When a buffer is available, NetReceive will call netReceive:newSamples:leftright: of its delegate. A stopSampling message will stop the stream.

Data is pulled by an NSTimer loop. The NSTimer object runs in its own Run Loop in a separate high priority thread. This, in turn, means that the call back to push data to the delegate(netReceive:newSamples:leftright:)is also not running inside the main thread. Be sure that any calls to objects in the Cocoa's framework that are not thread safe (e.g., NSView and its subclasses, NSBezierPath, etc) are dispatched from the main thread (see for example the Oscilloscope.m in the NetReceive sample code).



Tasks

Creating instances

Assigning a delegate

Setting service patrameters

Getting network patrameters

Starting and stopping sampling

Receiving sampled data

Network notifications



Instance Methods


delegate

Returns the delegate object of NetReceive.

- (id)delegate

Return Value

The current delegate object, or nil if no delegate has been set.



initWithAddress:port:delegate:samplesPerBuffer

Initializes and returns a newly allocated NetReceive object with the specified IP address and port number, delegate and the number of samples per call back to the delegate.

- (id)initWithAddress:(const char*)ipAddress port:(int)portNumber delegate:(id)inDelegate samplesPerBuffer:(int)samplesPerBuffer

Parameters

ipAddress
A C string that has the IP address of the AUNetSend service, e.g., "192.168.1.1"

portNumber
A port number of the AUNetSend service. Core Audio uses 52800 as the port number if a AUNetSend component did not set its own port number.

inDelegate
The delegate that NetReceive sends new data buffers to. If -init is called instead of -initWithService, the delegate is set to nil. You can also use -setDelegate to set a delegate.

samplesPerBuffer
The suggested buffer size that NetReceive sends to the delegate. If -init is called instead of -initWithService, the number of samples is set to 512.


Return Value

An initialized NetReceive object, or nil if an AUNetReceive component could not be created.



initWithService:delegate:samplesPerBuffer

Initializes and returns a newly allocated NetReceive object with the specified service name, delegate and the number of samples per call back to the delegate.

- (id)initWithService:(NSString*)serviceName delegate:(id)inDelegate samplesPerBuffer:(int)samplesPerBuffer

Parameters

serviceName
The Bonjour service name of the AUNetSend component that NetReceive is connecting to. If -init is called instead of -initWithService, the service name will be set to AUNetSend.

inDelegate
The delegate that NetReceive sends new data buffers to. If -init is called instead of -initWithService, the delegate is set to nil. You can also use -setDelegate to set a delegate.

samplesPerBuffer
The suggested buffer size that NetReceive sends to the delegate. If -init is called instead of -initWithService, the number of samples is set to 512.


Return Value

An initialized NetReceive object, or nil if an AUNetReceive component could not be created.



ip

Returns the IP address that Bonjour has resolved.

- (const char*)ip

Return Value

The string is usually in the form of "192.168.1.234".



port

Returns the port number that Bonjour has resolved.

- (int)port

Return Value

The number is usually 52800.



setAddress:port:

Sets and returns a newly allocated NetReceive object with the specified IP address and port number, delegate and the number of samples per call back to the delegate.

- (Boolean)setAddress:(const char*)ipAddress port:(int)portNumber

Parameters

ipAddress
A C string that has the IP address of the AUNetSend service, e.g., "192.168.1.1"

portNumber
A port number of the AUNetSend service. Core Audio uses 52800 as the port number if a AUNetSend component did not set its own port number.


Return Value

Returns true if successful.



setDelegate:

Sets the delegate object that is to receive data buffers from NetReceive. The delegate can also be set in - initWithService:delegate:samplesPerBuffer:.

- (void)setDelegate:(id)anObject

Parameters

anObject
The new delegate object.



setPassword:

Sets the password for the AUNetSend stream.

- (void)setPassword(NSString*)password

Parameters

password
The new password.

Discussion

NetReceive is initialized with no password. The password for a secure stream can set by sending setPassword: to the receiver.



setServiceName:

Sets the Bonjour service name for the AUNetSend stream that the receiver is connecting to.

- (void)setServiceName:(NSString*)name

Parameters

name
The Bonjour service name.

Discussion

The service name can be set during initialization by initializing using initWithService:delegate:samplesPerBuffer:. The service name can be changed anytime by calling setServiceName:.



startSampling

Starts the NetReceive object. The delegate should be set up to receive netReceive:newSamples:left:right calls that NetReceive sends the audio buffers to.

- (Boolean)startSampling

Return Value

NetReceive returns false if for some reason it could not start the output stream.



stopSampling

Stops the NetReceive object.

- (void)stopSampling



Delegate Methods



netReceive:newSamples:left:right:

invoked when NetReceive has a new buffer for the delegate.

- (void)netReceive:(NetReceive*)aNetReceive newSamples:(int)samplesPerBuffer left:(float*)leftBuffer right:(float*)rightBuffer

Parameters

aNetReceive
The NetReceive object that is sending the buffers. The delegate can use this to distinguish between multiple NetReceive objects.

samplesPerBuffer
This is the number of samples that is available. NetReceive uses stereo streams, each with its own floating point buffer.

leftBuffer
The left channel's buffer.

rightBuffer
The right channel's buffer.



netReceive:addressChanged:port:

invoked when NetReceive has resolved the IP address for the service name that it received.

- (void)netReceive:(NetReceive*)aNetReceive addressChanged:(const char*)address port:(int)port

Parameters

aNetReceive
The NetReceive object that reporting the change. The delegate can use this to distinguish between multiple NetReceive objects.

address
See -ip above.

port
See -port above.



netReceive:disconnectedFromAddress:port:

invoked when NetReceive has lost a connection to its service.

- (void)netReceive:(NetReceive*)aNetReceive disconnectedFromAddress:(const char*)address port:(int)port

Parameters

aNetReceive
The NetReceive object that reporting the change. The delegate can use this to distinguish between multiple NetReceive objects.

address
See -ip above.

port
See -port above.