Hyperledger Fabric SDK for node.js

Class: ChannelEventHub

ChannelEventHub

new ChannelEventHub(channel, peer)

Constructs a ChannelEventHub object
Parameters:
Name Type Description
channel Channel An instance of the Channel class were this ChannelEventHub will receive blocks
peer Peer Optional. An instance of the Peer class this ChannelEventHub connects.
Returns:
An instance of this class
Type
ChannelEventHub

Methods

checkConnection(force_reconnect)

Returns if the stream is ready. and will attempt a restart when forced
Parameters:
Name Type Description
force_reconnect boolean attempt to reconnect if the stream is not in the 'READY' state

close()

Disconnects the ChannelEventHub from the fabric peer service. Will close all event listeners and send an EventHubDisconnectError object with the message "ChannelEventHub has been shutdown" to all listeners that provided an "onError" callback.

connect(options, connectCallback)

Establishes a connection with the fabric peer service. The connection will be established asynchronously. If the connection fails to get established, the application will be notified via the 'connectCallback' provided. Additionally the error callbacks from the registerXXXEvent() methods will be notified if provided. It is recommended that an application relay on 'connectCallback' to determine connect status and relay on the 'errCallback' of the event listeners for runtime connection issues. Register event listeners and the error callbacks by calling any one of the registerBlockEvent, registerTxEvent or registerChaincodeEvent methods, after calling connect().
Parameters:
Name Type Description
options ConnectOptions | boolean Optional. If of type boolean then it will be assumed to how to connect to receive full (true) or filtered (false) blocks.
connectCallback function Optional. This callback will report completion of the connection to the peer or will report any errors encountered during connection to the peer. When there is an error, this ChannelEventHub will be shutdown (disconnected). Callback function should take two parameters as (error, value).

disconnect()

Disconnects the ChannelEventHub from the peer event source. Will close all event listeners and send an EventHubDisconnectError object with the message "ChannelEventHub has been shutdown" to all listeners that provided an "onError" callback.

generateUnsignedRegistration(options)

Generate the unsigned fabric service registration, this should be signed by the identity's private key.
Parameters:
Name Type Description
options EventHubRegistrationRequest the options for register this ChannelEventHub with the fabric peer service. Notice the options should contain either both identity and txId or both certificate and mspId
Returns:
the byte array contains the registration payload to be signed.
Type
Buffer

getName()

Return the name of this ChannelEventHub, will be the name of the associated peer.

getPeerAddr()

Return the peer url

isconnected()

Is this ChannelEventHub connected to the fabric service?
Returns:
True if connected to the event source, false otherwise
Type
boolean

reconnect(options, connectCallback)

Reestablishes a connection with the fabric peer service.
Parameters:
Name Type Description
options ConnectOptions Optional.
connectCallback function Optional. This callback will report completion of the connection to the peer or will report any errors encountered during connection to the peer. When there is an error, this ChannelEventHub will be shutdown (disconnected). Callback function should take two parameters as (error, value).

registerBlockEvent(onEvent, onError, options)

Register a listener to receive all block committed to this channel. The listener's "onEvent" callback gets called on the arrival of every block.

An error may occur in the connection establishment which runs asynchronously. The best practice would be to provide an "onError" callback to be notified when this ChannelEventHub has an issue.
Parameters:
Name Type Description
onEvent function Callback function that takes a single parameter of a Block object
onError function Optional callback function to be notified when this ChannelEventHub is shutdown. The shutdown may be caused by a network or connection error, by a call to the "disconnect()" method or when the fabric service ends the connection this ChannelEventHub. This callback will also be called when the ChannelEventHub is shutdown due to the last block being received if replaying and requesting the endBlock to be 'newest'.
options RegistrationOpts Options on the registrations to allow for start and end block numbers, automatically unregister and automatically disconnect.
Returns:
This is the block registration number that must be used to unregister this block listener. see unregisterBlockEvent()
Type
int

registerChaincodeEvent(chaincode_id, event_name, onEvent, onError, options)

Register a listener to receive chaincode events.

An error may occur in the connection establishment which runs asynchronously. The best practice would be to provide an "onError" callback to be notified when this ChannelEventHub has an issue.
Parameters:
Name Type Description
chaincode_id string Id of the chaincode of interest
event_name string | RegExp The exact name of the chaincode event or regular expression that will be matched against the name given to the target chaincode's call stub.SetEvent(name, payload))
onEvent function callback function for matched events. It will be called with four parameters when not using "as_array".
  • ChaincodeEvent - The chaincode event as produced by the chaincode,
  • {Long} - the block number that contains this chaincode event
  • {string} - the transaction ID that contains this chaincode event
  • {string} - the transaction status of the transaction that contains this chaincode event
When using "as_array: true" option, there will be one parameter of an array of an event objects with the above values which may be used as in the example below.
onError function Optional callback function to be notified when this ChannelEventHub is shutdown. The shutdown may be caused by a network or connection error, by a call to the "disconnect()" method or when the fabric service ends the connection this ChannelEventHub. This callback will also be called when the ChannelEventHub is shutdown due to the last block being received if replaying and requesting the endBlock to be 'newest'.
options RegistrationOpts Options on the registrations to allow for start and end block numbers, automatically unregister and automatically disconnect. Chaincode event listeners may also use the "as_array" option to indicate that all the chaincode events found that match this definition be sent to the callback as an array or call the callback for each one individually.
Returns:
An object that should be treated as an opaque handle used to unregister (see unregisterChaincodeEvent())
Type
Object
Example

Chaincode callback to process events when as_array:true 

function myCallback(...events) {
          for ({chaincode_event, block_num, tx_id, tx_status} of events) {
              // process the chaincode event
          }
       }

registerTxEvent(txid, onEvent, onError, options)

Register a callback function to receive a notification when the transaction by the given id has been committed into a block. Using the special string 'all' will indicate that this listener will notify (call) the callback for every transaction received from the fabric service.

An error may occur in the connection establishment which runs asynchronously. The best practice would be to provide an "onError" callback to be notified when this ChannelEventHub has an issue.
Parameters:
Name Type Description
txid string Transaction id string or 'all'
onEvent function Callback function that takes a parameter of transaction ID, a string parameter indicating the transaction status, and the block number of this transaction committed to the ledger
onError function Optional callback function to be notified when this ChannelEventHub is shutdown. The shutdown may be caused by a network or connection error, by a call to the "disconnect()" method or when the fabric event service ends the connection this ChannelEventHub. This callback will also be called when the ChannelEventHub is shutdown due to the last block being received if replaying and requesting the endBlock to be 'newest'.
options RegistrationOpts Options on the registrations to allow for start and end block numbers, automatically unregister and automatically disconnect.
Returns:
The transaction ID that was used to register this event listener. May be used to unregister this event listener.
Type
string

unregisterBlockEvent(block_registration_number, throwError)

Unregister the block event listener using the block registration number that is returned by the call to the registerBlockEvent() method.
Parameters:
Name Type Description
block_registration_number int The block registration number that was returned during registration.
throwError boolean Optional - throw an error if the block registration does not exist, default is to not throw an error

unregisterChaincodeEvent(listener_handle, throwError)

Unregister the chaincode event listener represented by the listener_handle object returned by the registerChaincodeEvent() method
Parameters:
Name Type Description
listener_handle Object The handle object returned from the call to registerChaincodeEvent.
throwError boolean Optional - throw an error if the chaincode event registration does not exist, default is to not throw an error

unregisterTxEvent(txid, throwError)

Unregister transaction event listener for the transaction id.
Parameters:
Name Type Description
txid string The transaction id
throwError boolean Optional - throw an error if the transaction registration does not exist, default is to not throw an error