diff --git a/bindings/broadcast.go b/bindings/broadcast.go index 75403e85ad5504603f7ac50f9e2cbdea4dff2be9..d2773904333e46902c85166f66ec5a05a4e3ee91 100644 --- a/bindings/broadcast.go +++ b/bindings/broadcast.go @@ -25,6 +25,7 @@ type Channel struct { } // ChannelDef is the bindings representation of an elixxir/crypto broadcast.Channel object. +// // Example JSON: // {"Name": "My broadcast channel", // "Description":"A broadcast channel for me to test things", @@ -39,6 +40,7 @@ type ChannelDef struct { } // BroadcastMessage is the bindings representation of a broadcast message. +// // Example JSON: // {"RoundID":42, // "EphID":[0,0,0,0,0,0,24,61], @@ -50,6 +52,7 @@ type BroadcastMessage struct { } // BroadcastReport is the bindings representation of the info on how a broadcast message was sent +// // Example JSON: // {"RoundID":42, // "EphID":[0,0,0,0,0,0,24,61] @@ -59,22 +62,25 @@ type BroadcastReport struct { EphID ephemeral.Id } -// BroadcastListener is the public function type bindings can use to listen for broadcast messages -// Accepts the result of calling json.Marshall on a BroadcastMessage object +// BroadcastListener is the public function type bindings can use to listen for broadcast messages. +// It accepts the result of calling json.Marshal on a BroadcastMessage object. type BroadcastListener interface { Callback([]byte, error) } -// NewBroadcastClient creates a bindings-layer broadcast channel & starts listening for new messages -// Accepts a client ID, broadcast method, JSON marshalled channel definition & a BroadcastListener interface -func NewBroadcastClient(clientID int, rawDef []byte) (*Channel, error) { - cl, err := cmixTrackerSingleton.get(clientID) +// NewBroadcastChannel creates a bindings-layer broadcast channel & starts listening for new messages +// +// Params +// - cmixId - internal ID of cmix +// - channelDefinition - JSON marshalled ChannelDef object +func NewBroadcastChannel(cmixId int, channelDefinition []byte) (*Channel, error) { + c, err := cmixTrackerSingleton.get(cmixId) if err != nil { return nil, err } def := &ChannelDef{} - err = json.Unmarshal(rawDef, def) + err = json.Unmarshal(channelDefinition, def) if err != nil { return nil, errors.WithMessage(err, "Failed to unmarshal underlying channel definition") } @@ -94,7 +100,7 @@ func NewBroadcastClient(clientID int, rawDef []byte) (*Channel, error) { Description: def.Description, Salt: def.Salt, RsaPubKey: chanPubLoaded, - }, cl.api.GetCmix(), cl.api.GetRng()) + }, c.api.GetCmix(), c.api.GetRng()) if err != nil { return nil, errors.WithMessage(err, "Failed to create broadcast channel client") } @@ -102,6 +108,12 @@ func NewBroadcastClient(clientID int, rawDef []byte) (*Channel, error) { return &Channel{ch: ch}, nil } +// Listen registers a BroadcastListener for a given method. +// This allows users to handle incoming broadcast messages. +// +// Params: +// - l - BroadcastListener object +// - method - int corresponding to broadcast.Method constant, 0 for symmetric or 1 for asymmetric func (c *Channel) Listen(l BroadcastListener, method int) error { broadcastMethod := broadcast.Method(method) listen := func(payload []byte, @@ -117,7 +129,7 @@ func (c *Channel) Listen(l BroadcastListener, method int) error { return c.ch.RegisterListener(listen, broadcastMethod) } -// Broadcast sends a given payload over the broadcast channel using symmetric broadcast +// Broadcast sends a given payload over the broadcast channel using symmetric broadcast. func (c *Channel) Broadcast(payload []byte) ([]byte, error) { rid, eid, err := c.ch.Broadcast(payload, cmix.GetDefaultCMIXParams()) if err != nil { @@ -129,8 +141,8 @@ func (c *Channel) Broadcast(payload []byte) ([]byte, error) { }) } -// BroadcastAsymmetric sends a given payload over the broadcast channel using asymmetric broadcast -// Requires a private key +// BroadcastAsymmetric sends a given payload over the broadcast channel using asymmetric broadcast. +// This mode of encryption requires a private key. func (c *Channel) BroadcastAsymmetric(payload, pk []byte) ([]byte, error) { pkLoaded, err := rsa.LoadPrivateKeyFromPem(pk) if err != nil { @@ -146,17 +158,17 @@ func (c *Channel) BroadcastAsymmetric(payload, pk []byte) ([]byte, error) { }) } -// MaxPayloadSize returns the maximum possible payload size which can be broadcast +// MaxPayloadSize returns the maximum possible payload size which can be broadcast. func (c *Channel) MaxPayloadSize() int { return c.ch.MaxPayloadSize() } -// MaxAsymmetricPayloadSize returns the maximum possible payload size which can be broadcast +// MaxAsymmetricPayloadSize returns the maximum possible payload size which can be broadcast. func (c *Channel) MaxAsymmetricPayloadSize() int { return c.ch.MaxAsymmetricPayloadSize() } -// Get returns the result of calling json.Marshal on a ChannelDef based on the underlying crypto broadcast.Channel +// Get returns the result of calling json.Marshal on a ChannelDef based on the underlying crypto broadcast.Channel. func (c *Channel) Get() ([]byte, error) { def := c.ch.Get() return json.Marshal(&ChannelDef{ @@ -167,7 +179,7 @@ func (c *Channel) Get() ([]byte, error) { }) } -// Stop stops the channel from listening for more messages +// Stop stops the channel from listening for more messages. func (c *Channel) Stop() { c.ch.Stop() }