JSDoc: Class: DebuggerTransport

# Class: DebuggerTransport

## DebuggerTransport(input, output, nsIAsyncOutputStream) → {Promise}

#### new DebuggerTransport(input, output, nsIAsyncOutputStream) → {Promise}

An adapter that handles data transfers between the debugger client and server. It can work with both nsIPipe and nsIServerSocket transports so long as the properly created input and output streams are specified. (However, for intra-process connections, LocalDebuggerTransport, below, is more efficient than using an nsIPipe pair with DebuggerTransport.)

##### Parameters:

Name | Type | Description
--- | --- | ---
`input` | nsIAsyncInputStream | The input stream.
- - `output` | nsIAsyncOutputStream | The output stream. Given a DebuggerTransport instance dt: 1) Set dt.hooks to a packet handler object (described below). 2) Call dt.ready() to begin watching for input packets. 3) Call dt.send() / dt.startBulkSend() to send packets. 4) Call dt.close() to close the connection, and disengage from the event loop. A packet handler is an object with the following methods: onPacket(packet) - called when we have received a complete packet. |packet| is the parsed form of the packet --- a JavaScript value, not a JSON-syntax string. onBulkPacket(packet) - called when we have switched to bulk packet receiving mode. |packet| is an object containing: actor: Name of actor that will receive the packet type: Name of actor's method that should be called on receipt length: Size of the data to be read stream: This input stream should only be used directly if you
            can ensure that you will read exactly |length| bytes and
            will not close the stream when reading is complete
  - done: If you use the stream directly (instead of |copyTo|
            below), you must signal completion by resolving/rejecting
            this deferred.  If it's rejected, the transport will
            be closed.  If an Error is supplied as a rejection value,
            it will be logged via |dump|.  If you do use |copyTo|,
            resolving is taken care of for you when copying completes.
  - copyTo: A helper function for getting your data out of the
            stream that meets the stream handling requirements above,
            and has the following signature:
`nsIAsyncOutputStream` | output | The stream to copy to.

Source:
  - transport.js, line 111

##### Returns:

The promise is resolved when copying completes or rejected if any (unexpected) errors occur. This object also emits "progress" events for each chunk that is copied. See stream-utils.js.

- onClosed(reason) - called when the connection is closed. |reason| is an optional nsresult or object, typically passed when the transport is closed due to some error in a underlying stream.

See ./packets.js and the Remote Debugging Protocol specification for more details on the format of these packets.

Type
  Promise

### Members

#### _currentOutgoing

The currently outgoing packet (at the top of the queue).

Source:
  - transport.js, line 242

### Methods

#### _destroyAllOutgoing()

Clear the entire outgoing queue.

Source:
  - transport.js, line 321

#### _destroyIncoming()

Remove all handlers and references related to the current incoming packet, either because it is now complete or because the transport is closing.

Source:
  - transport.js, line 527

#### _finishCurrentOutgoing()

Remove the current outgoing packet from the queue upon completion.

Source:
  - transport.js, line 311

#### _flushIncoming()

If the incoming packet is done, log it as needed and clear the buffer.

Source:
  - transport.js, line 482

#### _flushOutgoing()

Flush data to the outgoing stream. Waits until the output stream notifies us that it is ready to be written to (via onOutputStreamReady).

Source:
  - transport.js, line 251

#### _onBulkReadReady()

Handler triggered by an incoming BulkPacket entering the |read| phase for the stream portion of the packet. Delivers info about the incoming streaming data to this.hooks.onBulkPacket. See the main comment on the transport at the top of this file for more details.

Source:
  - transport.js, line 512

#### _onJSONObjectReady()

Handler triggered by an incoming JSONPacket completing it's |read| method. Delivers the packet to this.hooks.onPacket.

Source:
  - transport.js, line 496

#### _processIncoming() → {boolean}

Process the incoming data. Will create a new currently incoming Packet if needed. Tells the incoming Packet to read as much data as it can, but reading may not complete. The Packet signals that its data is ready for delivery by calling one of this transport's _onReady methods (see ./packets.js and the _onReady methods below).

Source:
  - transport.js, line 398

##### Returns:

Whether incoming stream processing should continue for any remaining data.

Type
  boolean

#### _readHeader() → {boolean}

Read as far as we can into the incoming data, attempting to build up a complete packet header (which terminates with ":"). We'll only read up to PACKET_HEADER_MAX characters.

Source:
  - transport.js, line 456

##### Returns:

True if we now have a complete header.

Type
  boolean

#### _waitForIncoming()

Asks the input stream to notify us (via onInputStreamReady) when it is ready for reading.

Source:
  - transport.js, line 342

#### close(reasonopt)

Close the transport.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`reason` | nsresult | object | <optional> | The status code or error message that corresponds to the reason for closing the transport (likely because a stream closed or failed).

Source:
  - transport.js, line 219

#### onInputStreamReady()

Called when the stream is either readable or closed.

Source:
  - transport.js, line 371

#### onOutputStreamReady()

This is called when the output stream is ready for more data to be written. The current outgoing packet will attempt to write some amount of data, but may not complete.

Source:
  - transport.js, line 290

#### pauseIncoming()

Pause this transport's attempts to read from the input stream. This is used when we've temporarily handed off our input stream for reading bulk data.

Source:
  - transport.js, line 354

#### pauseOutgoing()

Pause this transport's attempts to write to the output stream. This is used when we've temporarily handed off our output stream for writing bulk data.

Source:
  - transport.js, line 272

#### ready()

Initialize the input stream for reading. Once this method has been called, we watch for packets on the input stream, and pass them to the appropriate handlers via this.hooks.

Source:
  - transport.js, line 333

#### resumeIncoming()

Resume this transport's attempts to read from the input stream.

Source:
  - transport.js, line 361

#### resumeOutgoing()

Resume this transport's attempts to write to the output stream.

Source:
  - transport.js, line 279

#### send()

Transmit an object as a JSON packet.

This method returns immediately, without waiting for the entire packet to be transmitted, registering event handlers as needed to transmit the entire packet. Packets are transmitted in the order they are passed to this method.

Source:
  - transport.js, line 144

#### startBulkSend(header, input) → {Promise|Promise}

Transmit streaming data via a bulk packet.

This method initiates the bulk send process by queuing up the header data. The caller receives eventual access to a stream for writing.

N.B.: Do not attempt to close the stream handed to you, as it will continue to be used by this transport afterwards. Most users should instead use the provided |copyFrom| function instead.

##### Parameters:

Name | Type | Description
--- | --- | ---
`header` | Object | This is modeled after the format of JSON packets above, but does not actually contain the data, but is instead just a routing header:
      - actor:  Name of actor that will receive the packet
      - type:   Name of actor's method that should be called on receipt
      - length: Size of the data to be sent
`input` | nsIAsyncInputStream | The stream to copy from.

Source:
  - transport.js, line 201

##### Returns:

- The promise will be resolved when you are allowed to write to the stream with an object containing:

        - stream:   This output stream should only be used directly
                    if you can ensure that you will write exactly
                    |length| bytes and will not close the stream when
                     writing is complete.
        - done:     If you use the stream directly (instead of
                    |copyFrom| below), you must signal completion by
                    resolving/rejecting this deferred.  If it's
                    rejected, the transport will be closed.  If an
                    Error is supplied as a rejection value, it will
                    be logged via |dump|.  If you do use |copyFrom|,
                    resolving is taken care of for you when copying
                    completes.
        - copyFrom: A helper function for getting your data onto the
                    stream that meets the stream handling requirements
                    above, and has the following signature:

  Type
    Promise

- The promise is resolved when copying completes or rejected if any (unexpected) errors occur. This object also emits "progress" events for each chunkthat is copied. See stream-utils.js.

  Type
    Promise