APIs to manipulate attachments on the specific context

If the specific context has attachments, the session object allows the manipulation of attachments through operations by following the session.context.attachment.operation() syntax.

context

The context that a session object provides access to. It can be one of the predefined contexts or a named context that is retrieved by the session.name() API.

operation

An API that is used with contexts. The following APIs are supported.

APIs to manipulate the specified attachment body.
APIs to manipulate the specified attachment header.
- get()
- remove()
- set()

create()

Create an attachment on the specific context.

Syntax

session.context.attachment.create(identifier,header,data,function(error){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, output, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to create. This parameter must be a string or number. If this parameter is a string, you can construct it with Content-ID, Content-Location, and the thismessage protocol. If this parameter is a number, it indicates the attachment index that starts from 0.
header: The name of a header object. This parameter must be a JSON object.
data: The content of the created attachment.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you create the attachment, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.

Guidelines

Guidelines for constructing the identifier parameter.

You can construct the identifier parameter with Content-ID, Content-Location, and the thismessage protocol. The most common method for identifying an attachment is to specify an attachment with a globally unique Content-ID header.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

var header_object = {
  "Content-Transfer-Encoding": "base64",
  "Content-Type": "text/plain"
};

var data = XML.parse("<foo>bar</foo>");
session.output.attachment.create('cid:newatt1', header_object, data, function(error) {
  if (error) {
    console.error('fail to create new attachment '+error);
  }
});

get()

Gets the header value of an attachment on the specific context.

Syntax

session.context.attachment.get([identifier,][name,]function(error,value){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. When this parameter is empty, return all header objects of the attachment in the format of array of objects. Otherwise, it must be a string or number. If this parameter is a string, you can construct it with Content-ID, Content-Location, and the thismessage protocol. If this parameter is a number, it indicates the attachment index that starts from 0.
name: The name of the header to get. When this parameter is empty, return the whole header object. Otherwise, this parameter must be a string.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you get the header value of the attachment, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.
value: The header value of an attachment that is obtained.

Guidelines

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Examples

Get the value of the Content-Type header of the attachment that is identified by cid:att1.

session.input.attachment.get('cid:att1', 'content-type', function(error, value) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(value);
  }
});

Get the value of the Content-Type header of the attachment that is identified by the index value of zero.

session.input.attachment.get(0, 'content-type', function(error, value) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(value);
  }
});

readAsBuffer()

Reads the specified attachment on the specific context and returns the contents in binary as a Buffer object.

Syntax

session.context.attachment.readAsBuffer(identifier,function(error,buffer){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
error: The error object that is returned by the readAsBuffer() API. The error contains error information only if an error occurred. In the asynchronous callback, before you use the contents of the bufferObject, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.
buffer: The Buffer object that contains a binary representation of the context attachment that is read.

Guidelines

The readAsBuffer() API reads a document from an attachment on the specific context and returns the contents in binary as a Buffer object. The contents are any type of data, including JSON and XML.

If the context attachment is binary (either text or HTML), or if the context attachment has an unknown type, use the readAsBuffer() or readAsBuffers() API. The Buffer or Buffers objects are processed when they are read. Use readAsBuffer() or readAsBuffers() according to the context attachment size.
- When the context attachment is small, use the readAsBuffer() API.
- When the context attachment is large, use the readAsBuffers() API.
If the context attachment is a JSON document, use the readAsJSON() API.

The readAsBuffer() API requires a contiguous memory allocation. The readAsBuffer() API is faster but is more demanding on the memory system. The readAsBuffers() API does not require contiguous memory to populate the Buffers object.

Text and HTML data is manipulated by using Buffer and string interfaces. They are read as a Buffer and are either converted to a string or manipulated directly by using the Buffer API.

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Read the attachment that is identified by 'cid:att1' on the specific context and returns the contents in binary as a Buffer object. When the context attachment is read and an error occurs, handle the error. If no error occurs, continue processing the binary data read.

session.input.attachment.readAsBuffer('cid:att1', function(error, data) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(data);
  }
});

readAsBuffers()

Reads the specified attachment on the specific context and returns the contents in binary as a Buffers object.

Syntax

session.context.attachment.readAsBuffers(context,function(error,buffers){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you use the contents of the buffersObject, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.
buffers: The Buffers object that contains a binary representation of the context attachment that is read.

Guidelines

The readAsBuffers() API reads the specified attachment on the specific context and returns the contents in binary as a Buffers object. The contents are any type of data, including JSON and XML.

If the context attachment is binary (either text or HTML), or if the context attachment has an unknown type, use the readAsBuffer() or readAsBuffers() API. The Buffer or Buffers objects are processed when they are read. Use readAsBuffer() or readAsBuffers() according to the context attachment size.
- When the context attachment is small, use the readAsBuffer() API.
- When the context attachment is large, use the readAsBuffers() API.
If the context attachment is a JSON document, use the readAsJSON() API.

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Read the attachment that is identified by 'cid:att1' on the specific context and returns the contents in binary as a Buffers object. When the context attachment is read and an error occurs, handle the error. If no error occurs, continue processing the binary data read.

session.input.attachment.readAsBuffers('cid:att1', function(error, data) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(data);
  }
});

readAsJSON()

Reads a specified attachment on the specific context and returns the contents as a JSON object.

Syntax

session.context.attachment.readAsJSON(identifier,function(error,json){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you use the contents of the buffersObject, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.
json: The JSON document that contains a JSON representation of the context attachment that is read.

Guidelines

The readAsJSON() API parses the contents of the context attachment and returns the parsed information as a JSON object. If the content of the context attachment is not a JSON document, the parsing fails and an error object is returned.

The readAsJSON() API provides a quick way to create a JSON object that contains the context attachment information.

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Read the attachment that is identified by 'cid:att1' on the specific context and returns the contents as a JSON object. When the context attachment is read and an error occurs, handle the error. If no error occurs, continue processing the JSON data read.

session.input.attachment.readAsJSON('cid:att1', function(error, data) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(data);
  }
});

readAsXML()

Reads a specified attachment on the specific context and returns the contents as a NodeList.

Syntax

session.context.attachment.readAsXML(identifier,function(error,nodelist){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you use the contents of the NodeList, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined. An error occurs when the context attachment cannot be resolved as an XML DOM object.
nodelist: The NodeList object that contains the returned content of the specified context as XML nodes.

Guidelines

A function callback is asynchronously started when the context is read into a NodeList object. The NodeList object can be accessed with methods of the DOM API, XML, and other modules, as provided by GatewayScript. The NodeList object can contain zero or more nodes.

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Read the attachment that is identified by 'cid:att1' on the specific context and returns the contents as a NodeList.

session.input.attachment.readAsXML('cid:att1', function(error, data) {
  if (error) {
    session.output.write(error);
  }
  else {
    session.output.write(data);
  }
});

remove()

Removes the specified attachment header on the specific context.

Syntax

session.context.attachment.remove(identifier,header,function(error){})

Parameters

context: The context that a session object provides access to. The context can be output or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
header: The name of the attachment header to remove. This parameter must be a string.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you remove the attachment header, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.

Guidelines

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

set()

Sets the header value of an attachment on the specific context.

Syntax

session.context.attachment.set(identifier,name,value,function(error){})

Parameters

context: The context that a session object provides access to. The context can be output or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
name: The name of the attachment header to set. This parameter must be a string.
value: The value to set for the specified attachment header. This parameter must be a string.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before you set the attachment header value, check to ensure that no error occurred. The errorObject extends the Error object of the ECMAScript standard. To interrogate the message, use errorObject.errorMessage. If no error occurs, the error is undefined.

Guidelines

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

For the attachment that is identified by cid:att1, set the value of the Content-Type header as application/json.

session.output.attachment.set('cid:att1', 'content-type', 'application/json', function(error) {
  if (error) {
    session.output.write(error);
  }
});

strip()

Removes an attachment from a message on the specific context.

Syntax

session.context.attachment.strip(identifier,function(error){})

Parameters

context: The context that a session object provides access to. The context can be INPUT, input, output, or a named context that is retrieved by the session.name() API.
identifier: The unique identifier that represents an attachment to strip. This parameter must be a string or number. If this parameter is a string, you can construct it with Content-ID, Content-Location, and the thismessage protocol. If this parameter is a number, it indicates the attachment index that starts from zero.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, before the attachment is stripped, check to ensure that no error occurred.

Guidelines

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Remove the attachment that is identified by cid:att1 from a message.

var headerObj = {"Content-Type": "plain/text"};
session.output.attachment.create('cid:newatt1', headerObj, "Cest la vie", function(error) {
  if (error) { console.error("Attachment create fail: "+error); }
});

// At the same time, try to strip "cid:newatt1" - What happen then?
session.output.attachment.strip('cid:newatt1', function(error) {
  // does strip succeed or fail?
  if (error) { console.error("Attachment strip fail: "+error); }
});

// At the same time, try to set a new header to "cid:newatt1" - What happen then?
session.output.attachment.set('cid:newatt1', 'Content-Type', 'application/xml', function(error) {
  // If create is not yet completed, it will throw error.
  if (error) {console.error("Attachment set header fail: "+error);}
});

write()

Writes the object to the attachment on the specified output context.

Syntax

session.context.attachment.write(identifier,data,function(error){})

Parameters

context: The context that a session object provides access to. The context can be output or a named context.
identifier: The unique identifier that represents an attachment to access. This parameter must be a string or number. If this parameter is a string, construct with Content-ID, Content-Location, and the thismessage protocol. For detail, see the following guidelines. If this parameter is a number, it indicates the attachment index that starts from 0.
data: The data to write. The data can be any type, such as primitive type, object, buffer, XML, DOM.
error: The error object that contains error information only if an error occurred. In the asynchronous callback, check for an error to verify whether the data is successfully written to the attachment.

Guidelines

The write() API writes the object to the attachment on the specified output context. Calling the write() API to the same context overwrites the previous write() API calls to that context. In effect, the write() API can be called only one time on a context per session.

Objects differ in how they are written out.

Table 1. `Content-Type` values for data types.
Data type.	`Content-Type` value.
Strings are written as a UTF-8 encoded character array.	`text/plain; charset=UTF-8`
A Buffer is transferred directly to the context in binary.	`binary/octet-stream`
The Buffers structure is preserved as a list of binary buffers.	`binary/octet-stream`
A Node or NodeList is serialized as UTF-8 encoded XML strings.	`text/xml`
Other objects are written as UTF-8 encoded JSON format strings.	`application/json`

Guidelines for constructing the identifier parameter.

To construct the URI with the Content-ID header, use the cid:string format that identifies the attachment to access.
To construct the URI with the Content-Location header, specify an absolute or relative reference to a Content-Location value that identifies the attachment to access.
- With an absolute reference, use the http://www.someplace.com/string format. http://www.someplace.com must be defined as the Content-Location header in the message package.
- With a relative reference, use the /string format. Use the relative reference method when thee message package has no Content-Location header.
To construct the URI with the thismessage protocol, use the thismessage:/string format. Use thismessage protocol when the message package has no Content-Location header.

Example

Write a buffer object to the attachment that is identified by cid:att1.

var data = new Buffer("This is  buffer");
session.output.attachment.write('cid:att1', data, function(error) {
  if (error) {
    session.output.write(error);
  }
});