XX-4013/bindingsRoundList

bindings/broadcast.go

@@ -62,15 +62,19 @@ type BroadcastReport struct {
 	EphID ephemeral.Id
 }
 
-// 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.
+// BroadcastListener is the public function type bindings can use to listen for
+// broadcast messages.
+//
+// Parameters:
+//  - []byte - the JSON marshalled bytes of the BroadcastMessage object, which
+//    can be passed into WaitForRoundResult to see if the broadcast succeeded.
 type BroadcastListener interface {
 	Callback([]byte, error)
 }
 
 // NewBroadcastChannel creates a bindings-layer broadcast channel & starts listening for new messages
 //
-// Params
+// Parameters:
 //  - cmixId - internal ID of cmix
 //  - channelDefinition - JSON marshalled ChannelDef object
 func NewBroadcastChannel(cmixId int, channelDefinition []byte) (*Channel, error) {
@@ -111,9 +115,10 @@ func NewBroadcastChannel(cmixId int, channelDefinition []byte) (*Channel, error)
 // Listen registers a BroadcastListener for a given method.
 // This allows users to handle incoming broadcast messages.
 //
-// Params:
+// Parameters:
 //  - l - BroadcastListener object
-//  - method - int corresponding to broadcast.Method constant, 0 for symmetric or 1 for asymmetric
+//  - 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,
@@ -129,7 +134,12 @@ 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.
+//
+// Returns:
+//  - []byte - the JSON marshalled bytes of the BroadcastReport object, which
+//    can be passed into WaitForRoundResult to see if the broadcast succeeded.
 func (c *Channel) Broadcast(payload []byte) ([]byte, error) {
 	rid, eid, err := c.ch.Broadcast(payload, cmix.GetDefaultCMIXParams())
 	if err != nil {
@@ -141,8 +151,12 @@ func (c *Channel) Broadcast(payload []byte) ([]byte, error) {
 	})
 }
 
-// BroadcastAsymmetric sends a given payload over the broadcast channel using asymmetric broadcast.
-// This mode of encryption requires a private key.
+// BroadcastAsymmetric sends a given payload over the broadcast channel using
+// asymmetric broadcast. This mode of encryption requires a private key.
+//
+// Returns:
+//  - []byte - the JSON marshalled bytes of the BroadcastReport object, which
+//    can be passed into WaitForRoundResult to see if the broadcast succeeded.
 func (c *Channel) BroadcastAsymmetric(payload, pk []byte) ([]byte, error) {
 	pkLoaded, err := rsa.LoadPrivateKeyFromPem(pk)
 	if err != nil {

bindings/connect.go

@@ -79,7 +79,11 @@ func (c *Cmix) Connect(e2eId int, recipientContact, e2eParamsJSON []byte) (
 }
 
 // SendE2E is a wrapper for sending specifically to the Connection's
-// partner.Manager. Returns a marshalled E2ESendReport.
+// partner.Manager.
+//
+// Returns:
+//  - []byte - the JSON marshalled bytes of the E2ESendReport object, which can
+//    be passed into WaitForRoundResult to see if the send succeeded.
 func (c *Connection) SendE2E(mt int, payload []byte) ([]byte, error) {
 	rounds, mid, ts, err := c.connection.SendE2E(catalog.MessageType(mt), payload,
 		c.params.Base)
@@ -89,12 +93,11 @@ func (c *Connection) SendE2E(mt int, payload []byte) ([]byte, error) {
 	}
 
 	sr := E2ESendReport{
-		MessageID: mid.Marshal(),
-		Timestamp: ts.UnixNano(),
+		RoundsList: makeRoundsList(rounds...),
+		MessageID:  mid.Marshal(),
+		Timestamp:  ts.UnixNano(),
 	}
 
-	sr.RoundsList = makeRoundsList(rounds...)
-
 	return json.Marshal(&sr)
 }
 

bindings/delivery.go

@@ -70,7 +70,7 @@ type MessageDeliveryCallback interface {
 	EventCallback(delivered, timedOut bool, roundResults []byte)
 }
 
-// WaitForMessageDelivery allows the caller to get notified if the rounds a
+// WaitForRoundResult allows the caller to get notified if the rounds a
 // message was sent in successfully completed. Under the hood, this uses an API
 // that uses the internal round data, network historical round lookup, and
 // waiting on network events to determine what has (or will) occur.
@@ -83,24 +83,25 @@ type MessageDeliveryCallback interface {
 //
 // roundList is a JSON marshalled RoundsList or any JSON marshalled send report
 // that inherits a RoundsList object.
-func (c *Cmix) WaitForMessageDelivery(
+func (c *Cmix) WaitForRoundResult(
 	roundList []byte, mdc MessageDeliveryCallback, timeoutMS int) error {
-	jww.INFO.Printf("WaitForMessageDelivery(%s, _, %d)", roundList, timeoutMS)
+	jww.INFO.Printf("WaitForRoundResult(%s, _, %d)", roundList, timeoutMS)
 	rl, err := unmarshalRoundsList(roundList)
 	if err != nil {
-		return errors.Errorf("Failed to WaitForMessageDelivery callback due "+
-			"to bad Send Report: %+v", err)
+		return errors.Errorf("Failed to WaitForRoundResult callback due to "+
+			"bad Send Report: %+v", err)
 	}
 
 	if rl == nil || len(rl) == 0 {
-		return errors.Errorf("Failed to WaitForMessageDelivery callback due "+
-			"to invalid Send Report unmarshal: %s", roundList)
+		return errors.Errorf("Failed to WaitForRoundResult callback due to "+
+			"invalid Send Report unmarshal: %s", roundList)
 	}
 
 	f := func(allRoundsSucceeded, timedOut bool, rounds map[id.Round]cmix.RoundResult) {
 		results := make([]byte, len(rl))
-		jww.INFO.Printf("Processing WaitForMessageDelivery report "+
-			"success: %v, timeout: %v", allRoundsSucceeded, timedOut)
+		jww.INFO.Printf(
+			"Processing WaitForRoundResult report success: %t, timeout: %t",
+			allRoundsSucceeded, timedOut)
 		for i, r := range rl {
 			if result, exists := rounds[r]; exists {
 				results[i] = byte(result.Status)

bindings/e2eHandler.go

@@ -117,7 +117,8 @@ func (e *E2e) RemoveService(tag string) error {
 //  - e2eParams - the marshalled bytes of the e2e.Params object.
 //
 // Returns:
-//  - []byte - the marshalled bytes of the E2ESendReport object.
+//  - []byte - the JSON marshalled bytes of the E2ESendReport object, which can
+//    be passed into WaitForRoundResult to see if the send succeeded.
 func (e *E2e) SendE2E(messageType int, recipientId, payload,
 	e2eParams []byte) ([]byte, error) {
 	// Note that specifically these are the Base params from xxdk.E2EParams

bindings/group.go

@@ -132,7 +132,9 @@ func NewGroupChat(e2eID int,
 //    and may be nil. If nil the group will be assigned the default name.
 //
 // Returns:
-//  - []byte - a JSON-marshalled GroupReport.
+//  - []byte - the JSON marshalled bytes of the GroupReport object, which can be
+//    passed into WaitForRoundResult to see if the group request message send
+//    succeeded.
 func (g *GroupChat) MakeGroup(membership IdList, message, name []byte) (
 	[]byte, error) {
 
@@ -166,7 +168,9 @@ func (g *GroupChat) MakeGroup(membership IdList, message, name []byte) (
 //    This can be found in the report returned by GroupChat.MakeGroup.
 //
 // Returns:
-//  - []byte - a JSON-marshalled GroupReport.
+//  - []byte - the JSON marshalled bytes of the GroupReport object, which can be
+//    passed into WaitForRoundResult to see if the group request message send
+//    succeeded.
 func (g *GroupChat) ResendRequest(groupId []byte) ([]byte, error) {
 
 	// Unmarshal the group ID
@@ -205,7 +209,7 @@ func (g *GroupChat) ResendRequest(groupId []byte) ([]byte, error) {
 //
 // Parameters:
 //  - trackedGroupId - the ID to retrieve the Group object within the backend's
-//                     tracking system. This is received by GroupRequest.Callback.
+//    tracking system. This is received by GroupRequest.Callback.
 func (g *GroupChat) JoinGroup(trackedGroupId int) error {
 	// Retrieve group from singleton
 	grp, err := groupTrackerSingleton.get(trackedGroupId)
@@ -245,7 +249,9 @@ func (g *GroupChat) LeaveGroup(groupId []byte) error {
 //  - tag - the tag associated with the message. This tag may be empty.
 //
 // Returns:
-//  - []byte - a JSON marshalled GroupSendReport.
+//  - []byte - the JSON marshalled bytes of the GroupSendReport object, which
+//    can be passed into WaitForRoundResult to see if the group message send
+//    succeeded.
 func (g *GroupChat) Send(groupId,
 	message []byte, tag string) ([]byte, error) {
 	groupID, err := id.Unmarshal(groupId)

bindings/single.go

@@ -32,7 +32,8 @@ import (
 //  - responseCB - the callback that will be called when a response is received
 //
 // Returns:
-//  - []byte - JSON marshalled SingleUseSendReport
+//  - []byte - the JSON marshalled bytes of the SingleUseSendReport object,
+//    which can be passed into WaitForRoundResult to see if the send succeeded.
 func TransmitSingleUse(e2eID int, recipient []byte, tag string, payload,
 	paramsJSON []byte, responseCB SingleUseResponse) ([]byte, error) {
 	e2eCl, err := e2eTrackerSingleton.get(e2eID)
@@ -162,7 +163,9 @@ type Stopper interface {
 // received.
 //
 // Parameters:
-//  - callbackReport - JSON marshalled SingleUseCallbackReport
+//  - callbackReport - the JSON marshalled bytes of the SingleUseCallbackReport
+//    object, which can be passed into WaitForRoundResult to see if the send
+//    succeeded.
 type SingleUseCallback interface {
 	Callback(callbackReport []byte, err error)
 }
@@ -171,7 +174,9 @@ type SingleUseCallback interface {
 // clients into TransmitSingleUse.
 //
 // Parameters:
-//  - callbackReport - JSON marshalled SingleUseResponseReport
+//  - callbackReport - the JSON marshalled bytes of the SingleUseResponseReport
+//    object, which can be passed into WaitForRoundResult to see if the send
+//    succeeded.
 type SingleUseResponse interface {
 	Callback(responseReport []byte, err error)
 }

bindings/ud.go

@@ -305,7 +305,8 @@ type UdLookupCallback interface {
 //  - singleRequestParams - the JSON marshalled bytes of single.RequestParams
 //
 // Returns:
-//  - []byte - the JSON marshalled bytes of SingleUseSendReport
+//  - []byte - the JSON marshalled bytes of the SingleUseSendReport object,
+//    which can be passed into WaitForRoundResult to see if the send succeeded.
 func LookupUD(e2eID int, udContact []byte, cb UdLookupCallback,
 	lookupId []byte, singleRequestParamsJSON []byte) ([]byte, error) {
 
@@ -379,7 +380,8 @@ type UdSearchCallback interface {
 //  - singleRequestParams - the JSON marshalled bytes of single.RequestParams
 //
 // Returns:
-//  - []byte - the JSON marshalled bytes of SingleUseSendReport
+//  - []byte - the JSON marshalled bytes of the SingleUseSendReport object,
+//    which can be passed into WaitForRoundResult to see if the send succeeded.
 func SearchUD(e2eID int, udContact []byte, cb UdSearchCallback,
 	factListJSON []byte, singleRequestParamsJSON []byte) ([]byte, error) {