org.bitcoinj.core

Class AlertMessage

java.lang.Object

org.bitcoinj.core.Message

org.bitcoinj.core.AlertMessage

All Implemented Interfaces:

Serializable

public class AlertMessage
extends Message

Alerts are signed messages that are broadcast on the peer-to-peer network if they match a hard-coded signing key. The private keys are held by a small group of core Bitcoin developers, and alerts may be broadcast in the event of an available upgrade or a serious network problem. Alerts have an expiration time, data that specifies what set of software versions it matches and the ability to cancel them by broadcasting another type of alert.

The right course of action on receiving an alert is usually to either ensure a human will see it (display on screen, log, email), or if you decide to use alerts for notifications that are specific to your app in some way, to parse it. For example, you could treat it as an upgrade notification specific to your app. Satoshi designed alerts to ensure that software upgrades could be distributed independently of a hard-coded website, in order to allow everything to be purely peer-to-peer. You don't have to use this of course, and indeed it often makes more sense not to.

Before doing anything with an alert, you should check isSignatureValid().

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.bitcoinj.core.Message

Message.LazyParseException

Field Summary

Fields inherited from class org.bitcoinj.core.Message

checksum, cursor, length, MAX_SIZE, offset, params, parsed, parseLazy, parseRetain, payload, protocolVersion, recached, UNKNOWN_LENGTH

Constructor Summary

Constructors

Constructor and Description
AlertMessage(NetworkParameters params, byte[] payloadBytes)

Method Summary

Modifier and Type	Method and Description
long	getCancel() A marker that results in any alerts with an ID lower than this value to be considered cancelled.
String	getComment() This field is unused.
Date	getExpiration() The time at which the alert ceases to be relevant.
long	getId() The numeric identifier of this alert.
long	getMaxVer() The inclusive upper bound on software versions considered for the purposes of this alert.
long	getMinVer() The inclusive lower bound on software versions that are considered for the purposes of this alert.
long	getPriority() Provides an integer ordering amongst simultaneously active alerts.
Date	getRelayUntil() The time at which the alert should stop being broadcast across the network.
String	getReserved() This field is never used.
String	getStatusBar() A string that is intended to display in the status bar of the official GUI client.
long	getVersion()
boolean	isSignatureValid() Returns true if the digital signature attached to the message verifies.
protected void	parseLite() Perform the most minimal parse possible to calculate the length of the message payload.
void	setCancel(long cancel)
void	setComment(String comment)
void	setExpiration(Date expiration)
void	setId(long id)
void	setMaxVer(long maxVer)
void	setMinVer(long minVer)
void	setPriority(long priority)
void	setRelayUntil(Date relayUntil)
void	setReserved(String reserved)
void	setStatusBar(String statusBar)
String	toString()

Methods inherited from class org.bitcoinj.core.Message

adjustLength, bitcoinSerialize, bitcoinSerialize, ensureParsed, getHash, getMessageSize, getParams, isCached, isParsed, isRecached, maybeParse, unCache, unsafeBitcoinSerialize

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AlertMessage

public AlertMessage(NetworkParameters params,
                    byte[] payloadBytes)
             throws ProtocolException

Throws:

ProtocolException

Method Detail

toString

public String toString()

Overrides:

toString in class Object

isSignatureValid

public boolean isSignatureValid()

Returns true if the digital signature attached to the message verifies. Don't do anything with the alert if it doesn't verify, because that would allow arbitrary attackers to spam your users.

parseLite

protected void parseLite()
                  throws ProtocolException

Description copied from class: Message

Perform the most minimal parse possible to calculate the length of the message payload. This is only required for subclasses of ChildMessage as root level messages will have their length passed into the constructor.

Implementations should adhere to the following contract: If parseLazy = true the 'length' field must be set before returning. If parseLazy = false the length field must be set either within the parseLite() method OR the parse() method. The overriding requirement is that length must be set to non UNKNOWN_MESSAGE value by the time the constructor exits.

Specified by:

parseLite in class Message

Throws:

ProtocolException

getRelayUntil

public Date getRelayUntil()

The time at which the alert should stop being broadcast across the network. Note that you can still receive the alert after this time from other nodes if the alert still applies to them or to you.

setRelayUntil

public void setRelayUntil(Date relayUntil)

getExpiration

public Date getExpiration()

The time at which the alert ceases to be relevant. It should not be presented to the user or app administrator after this time.

setExpiration

public void setExpiration(Date expiration)

getId

public long getId()

The numeric identifier of this alert. Each alert should have a unique ID, but the signer can choose any number. If an alert is broadcast with a cancel field higher than this ID, this alert is considered cancelled.

Returns:

uint32

setId

public void setId(long id)

getCancel

public long getCancel()

A marker that results in any alerts with an ID lower than this value to be considered cancelled.

Returns:

uint32

setCancel

public void setCancel(long cancel)

getMinVer

public long getMinVer()

The inclusive lower bound on software versions that are considered for the purposes of this alert. The Satoshi client compares this against a protocol version field, but as long as the subVer field is used to restrict it your alerts could use any version numbers.

Returns:

uint32

setMinVer

public void setMinVer(long minVer)

getMaxVer

public long getMaxVer()

The inclusive upper bound on software versions considered for the purposes of this alert. The Satoshi client compares this against a protocol version field, but as long as the subVer field is used to restrict it your alerts could use any version numbers.

Returns:

setMaxVer

public void setMaxVer(long maxVer)

getPriority

public long getPriority()

Provides an integer ordering amongst simultaneously active alerts.

Returns:

uint32

setPriority

public void setPriority(long priority)

getComment

public String getComment()

This field is unused. It is presumably intended for the author of the alert to provide a justification for it visible to protocol developers but not users.

setComment

public void setComment(String comment)

getStatusBar

public String getStatusBar()

A string that is intended to display in the status bar of the official GUI client. It contains the user-visible message. English only.

setStatusBar

public void setStatusBar(String statusBar)

getReserved

public String getReserved()

This field is never used.

setReserved

public void setReserved(String reserved)

getVersion

public long getVersion()