CLARA URTEAGA GOLDSTEIN Intendente Nacional Jurídico

To handle responses to a message you have sent, you define callback handler functions in the message object itself. The target application cannot send a response message back to the sender unless the message object it received has the appropriate callback defined.

NOTE: The message callbacks are optional, and are not implemented by all message-enabled applications.

When your message is received by its target, the target application’s static BridgeTalk object’s onReceive

method processes that message, and can invoke one of the message object’s callbacks to return a

response. In each case, the messaging framework packages the response in a new message object, whose target application is the sender. Your callback functions receive this response message object as an argument.

➤ The result of an error in processing the message. This is handled by the onError callback. If an error occurs in processing the message body (as the result of a JavaScript syntax error, for

instance), the target application invokes the onError callback, passing a response message that

contains the error code and error message. If you do not have an onError callback defined, the error is

completely transparent. It can appear that the message has not been processed, since no result is ever returned to the onResult callback.

➤ A notification of receipt of the message. This is handled by the onReceived callback.

Message sending is asynchronous. Getting a true result from the send method does not guarantee that your message was actually received by the target application. If you want to be notified of the receipt of your message, define the onReceived callback in the message object. The target sends back the original message object to this callback, first replacing the body value with an empty string. ➤ The result of a time-out. This is handled by the onTimeout callback.

You can specify a number of seconds in a message object’s timeout property. If the message is not removed from the input queue for processing before the time elapses, it is discarded. If the sender has defined an onTimeout callback for the message, the target application sends a time-out message back to the sender.

➤ Intermediate responses. These are handled by the onResult callback.

The script that you send can send back intermediate responses by invoking the original message object’s sendResult() method. It can send data of any type, but that data is packaged into a body string

in a new message object, which is passed to your callback. See “Passing values between applications” on page 170.

➤ The final result of processing the message. This is handled by the onResult callback.

When it finishes processing your message, the target application can send back a result of any type. If you have sent a script, and the target application is using the default BridgeTalk.onReceive callback

to process messages, the return value is the final result of evaluating that script. In any case, the return value is packaged into a body string in a new message object, which is passed to your callback. See

“Passing values between applications” on page 170.

The following examples demonstrate how to handle simple responses and multiple responses, and how to integrate error handling with response handling.

Example: Receiving a simple response

In this example, an application script asks Adobe Bridge to find out how many files and folders are in a certain folder, which the evaluation of the script returns. (The default BridgeTalk.onReceive method processes this correctly.)

The onResult method saves that number in fileCountResult, a script-defined property of the message, for later use.

var bt = new BridgeTalk; bt.target = "bridge-3.0";

bt.body = "new Document(’C:\\BridgeScripts’); app.document.target.children.length;" bt.onResult = function( retObj ) {

processFileCount(retObj.body); }

CHAPTER 5: Interapplication Communication with Scripts Communicating through messages 169

Example: Handling any error

In this example, the onError handler re-throws the error message within the sending application. var bt = new BridgeTalk;

bt.onError = function (btObj) {

var errorCode = parseInt (btObj.headers ["Error-Code"]); throw new Error (errorCode, btObj.body);

}

Example: Handling expected errors and responses

This example creates a message that asks Adobe Bridge to return XMP metadata for a specific file. The

onResult method processes the data using a script-defined processFileSize function. Any errors are

handled by the onError method. For example, if the file requested is not an existing file, the resulting error

is returned to the onError method.

var bt = new BridgeTalk; bt.target = "bridge-3.0";

bt.body = "var tn = new Thumbnail(’C/MyPhotos/temp.gif’); tn.core.immediate.size;"

bt.onResult = function( resultMsg ) { processFileSize(resultMsg.body); }

bt.onError = function( errorMsg ) {

var errCode = parseInt (errorMsg.headers ["Error-Code"]); throw new Error (errCode, errorMsg.body);

}

bt.send();

Example: Setting up a target to send multiple responses

This example integrates the sending of multiple responses with the evaluation of a message body. It sets up a handler for a message such as the one sent in the following example.

The target application (Adobe Bridge) defines a static onReceive method to allow for a new type of message, which it calls an iterator. An iterator type of message expects the message.body to use the

iteration variable i within the script, so that different results are produced for each pass through the while

loop. Each result is sent back to the sending application with the sendResult() method. When the

message.body has finished processing its task, it sets a flag to end the while loop. // Code for processing the message and sending intermediate responses // in the target application (Adobe Bridge)

BridgeTalk.onReceive = function (message){ switch (message.type) {

case "iterator": done = false; i = 0;

while (!done) {

// the message.body uses "i" to produce different results // for each execution of the message.

// when done, the message.body sets "done" to true // so this onReceive method breaks out of the loop. message.sendResult(eval(message.body));

i++; } break;

default: //"ExtendScript" return eval( message.body ); }

Example: Setting up a sender to receive multiple responses

This example sends a message of the type iterator, to be handled by the onReceive handler in the

previous example, and processes the responses received from that target.

The sending application creates a message whose script (contained in the body string) iterates through all files in a specific folder (represented by an Adobe Bridge Thumbnail object), using the iterator variable i.

For each file in the folder, it returns file size data. For each contained folder, it returns -1. The last executed line in the script is the final result value for the message.

The onResult method of the message object receives each intermediate result, stores it into an array,

resArr, and processes it immediately using a script-defined function processInterResult.

// Code for send message and handling response

// in the sending application (any message-enabled application) var idx = 0;

var resArr = new Array; bt = new BridgeTalk; bt.target = "bridge"; bt.type = "iterator"; bt.body = "

var fld = new Thumbnail(Folder(’C/Junk’)); if (i == (fld.children.length - 1))

done = true; //no more files, end loop tn = fld.children[i];

if (tn.spec.constructor.name == ’File’) md = tn.core.immediate.size;

else md = -1; ";

// store intermediate results bt.onResult = function(rObj) { resArr[idx] = rObj.body; processInterResult(resArr[idx]); idx++;}; bt.onError = function(eObj) { bt.error = eObj.body }; bt.send();