Event Register
Create, modify or remove an event listener which can report server events via Event Wait. POST only.
Request:
- requestType is eventRegister
- event is one of multiple server events from the following list of event names: (optional, default is all possible events)
- Block.BLOCK_GENERATED
- Block.BLOCK_POPPED
- Block.BLOCK_PUSHED
- Peer.ADD_INBOUND
- Peer.ADDED_ACTIVE_PEER
- Peer.BLACKLIST
- Peer.CHANGED_ACTIVE_PEER
- Peer.DEACTIVATE
- Peer.NEW_PEER
- Peer.REMOVE
- Peer.REMOVE_INBOUND
- Peer.UNBLACKLIST
- Transaction.ADDED_CONFIRMED_TRANSACTIONS
- Transaction.ADDED_UNCONFIRMED_TRANSACTIONS
- Transaction.REJECT_PHASED_TRANSACTION
- Transaction.RELEASE_PHASED_TRANSACTION
- Transaction.REMOVE_UNCONFIRMED_TRANSACTIONS
- event is one of multiple server events (optional)
- add is true to add events to an existing listener (optional, omit if remove is true)
- remove is true to remove events from an existing listener (optional, omit if add is true)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
Note: To create a new event listener, omit both add and remove. To remove an existing event listener, set remove to true and omit event; all registered events will be removed, any outstanding Event Wait will be completed and the listener will be deactivated.
Note: An event listener is automatically deactivated whenever all registered events are removed or if Event Wait is not called frequently enough, according to the xin.apiEventTimeout property. The timeout is not precise; the removal process runs every xin.apiEventTimeout / 2 seconds, so that many extra seconds may elapse before removal; the first Event Wait call should be made immediately after registration to avoid deactivation.
Note: Each API user (with a unique address) can create only one event listener. When a new one is created, it will replace an existing one. The maximum number of unique users is controlled by the xin.maxEventUsers property.
Response:
- registered is true if the operation completed successfully
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)