signalReady

postal.fedx.signalReady() is the way for this local instance of postal to ping remote instances as the first step in federation. If the local instance of postal isn't ready - meaning it doesn't have a postal.instanceId() value - any attempts to signalReady will be queued up in the _signalQueue until the instance is ready (at which time the _signalQueue will be replayed). If the instance of postal is ready, signalReady iterates over each transport plugin and calls the transport-specific implementation of signalReady. (It's up to each transport to provide a concrete way to signal ready to remotes.) postal.fedx.signalReady() has six overloads:

// calling signalReady with no arguments
// any transport plugin will attempt to find their own targets via
// the transport-specific ""getTargets"" implementation. Any targets
// provided will receive a "federation.ping" message
postal.fedx.signalReady();

// calling signalReady and passing an onFederated callback
// the callback will be invoked for EACH remote that replies with
// a federation.pong message. This may change in the future.
postal.fedx.signalReady(function(federationInfo) {
    /*
    	federation info object looks something like:
    	{
    		ticket     : "pingTicket#",
    		instanceId : "remote postal instance Id",
    		source     : FederationClientDerivedProxyObject
    	}	
   	*/
});

// calling signalReady and passing the string name of the transport
// this tells only that transport to signal ready
postal.fedx.signalReady("xframe");

// calling signalReady and passing the transport name and a callback
postal.fedx.signalReady("xframe", onFederatedCallback);

// calling signalReady and passing an options argument
// the options argument should have keys the match the names of the
// transports which you want to signal ready. If you want to let the
// transport determine the targets, you simply pass "true". If you want
// to provide specific targets, you pass them as an array.
signalReady(
	{
		transportNameA : targetsForA,
		transportNameB : targetsForB,
		transportC     : true
	}
	[, callback]
);

// the callback argument above is option. Passing it makes the 6th overload

There is a lot of flexibility built into the postal.fedx.signalReady call, but more than likely you will typically use the first overload (no arguments) or just passing an onFederated callback as the only argument.