github.com/xmidt-org/webpa-common@v1.11.9/device/listener.go (about) 1 package device 2 3 import ( 4 "github.com/xmidt-org/wrp-go/v3" 5 ) 6 7 // EventType is the type of device-related event 8 type EventType uint8 9 10 const ( 11 // Connect indicates a successful device connection. After receipt of this event, the given 12 // Device is able to receive requests. 13 Connect EventType = iota 14 15 // Disconnect indicates a device disconnection. After receipt of this event, the given 16 // Device can no longer receive requests. 17 Disconnect 18 19 // MessageSent indicates that a message was successfully dispatched to a device. 20 MessageSent 21 22 // MessageReceived indicates that a message has been successfully received and 23 // dispatched to any goroutine waiting on it, as would be the case for a response. 24 MessageReceived 25 26 // MessageFailed indicates that a message could not be sent to a device, either because 27 // of a communications error or due to the device disconnecting. For each enqueued message 28 // at the time of a device's disconnection, there will be (1) MessageFailed event. 29 MessageFailed 30 31 // TransactionComplete indicates that a response to a transaction has been received, and the 32 // transaction completed successfully (at least as far as the routing infrastructure can tell). 33 TransactionComplete 34 35 // TransactionBroken indicates receipt of a message that had a transaction key for which there 36 // was no waiting transaction 37 TransactionBroken 38 39 InvalidEventString string = "!!INVALID DEVICE EVENT TYPE!!" 40 ) 41 42 var ( 43 // blankEvent is an Event in its initial state. Useful for quick state reset. 44 blankEvent Event 45 ) 46 47 func (et EventType) String() string { 48 switch et { 49 case Connect: 50 return "Connect" 51 case Disconnect: 52 return "Disconnect" 53 case MessageSent: 54 return "MessageSent" 55 case MessageReceived: 56 return "MessageReceived" 57 case MessageFailed: 58 return "MessageFailed" 59 case TransactionComplete: 60 return "TransactionComplete" 61 case TransactionBroken: 62 return "TransactionBroken" 63 default: 64 return InvalidEventString 65 } 66 } 67 68 // Event represents a single occurrence of interest for device-related applications. 69 // Instances of Event should be considered immutable by application code. Also, Event 70 // instances should not be stored across calls to a listener, as the infrastructure is 71 // free to reuse Event instances. 72 type Event struct { 73 // Type describes the kind of this event. This field is always set. 74 Type EventType 75 76 // Device refers to the device, possibly disconnected, for which this event is being set. 77 // This field is always set. 78 Device Interface 79 80 // Message is the WRP message relevant to this event. 81 // 82 // Never assume that it is safe to use this Message outside the listener invocation. Make 83 // a copy if this Message is needed by other goroutines or if it needs to be part of a long-lived 84 // data structure. 85 Message wrp.Typed 86 87 // Format is the encoding format of the Contents field 88 Format wrp.Format 89 90 // Contents is the encoded representation of the Message field. It is always set if and only if 91 // the Message field is set. 92 // 93 // Never assume that it is safe to use this byte slice outside the listener invocation. Make 94 // a copy if this byte slice is needed by other goroutines or if it needs to be part of a long-lived 95 // data structure. 96 Contents []byte 97 98 // Error is the error which occurred during an attempt to send a message. This field is only populated 99 // for MessageFailed events when there was an actual error. For MessageFailed events that indicate a 100 // device was disconnected with enqueued messages, this field will be nil. 101 Error error 102 } 103 104 // Listener is an event sink. Listeners should never modify events and should never 105 // store events for later use. If data from an event is needed for another goroutine 106 // or for long-term storage, a copy should be made. 107 type Listener func(*Event)