1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
// Copyright (c) 2017 Cisco and/or its affiliates.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package api
import (
"time"
)
// MessageType represents the type of a VPP message.
type MessageType int
const (
// RequestMessage represents a VPP request message
RequestMessage MessageType = iota
// ReplyMessage represents a VPP reply message
ReplyMessage
// EventMessage represents a VPP notification event message
EventMessage
// OtherMessage represents other VPP message (e.g. counters)
OtherMessage
)
// Message is an interface that is implemented by all VPP Binary API messages generated by the binapigenerator.
type Message interface {
// GetMessageName returns the original VPP name of the message, as defined in the VPP API.
GetMessageName() string
// GetMessageType returns the type of the VPP message.
GetMessageType() MessageType
// GetCrcString returns the string with CRC checksum of the message definition (the string represents a hexadecimal number).
GetCrcString() string
}
// DataType is an interface that is implemented by all VPP Binary API data types by the binapi_generator.
type DataType interface {
// GetTypeName returns the original VPP name of the data type, as defined in the VPP API.
GetTypeName() string
// GetCrcString returns the string with CRC checksum of the data type definition (the string represents a hexadecimal number).
GetCrcString() string
}
// ChannelProvider provides the communication channel with govpp core.
type ChannelProvider interface {
// NewAPIChannel returns a new channel for communication with VPP via govpp core.
// It uses default buffer sizes for the request and reply Go channels.
NewAPIChannel() (Channel, error)
// NewAPIChannelBuffered returns a new channel for communication with VPP via govpp core.
// It allows to specify custom buffer sizes for the request and reply Go channels.
NewAPIChannelBuffered(reqChanBufSize, replyChanBufSize int) (Channel, error)
}
// MessageDecoder provides functionality for decoding binary data to generated API messages.
type MessageDecoder interface {
// DecodeMsg decodes binary-encoded data of a message into provided Message structure.
DecodeMsg(data []byte, msg Message) error
}
// MessageIdentifier provides identification of generated API messages.
type MessageIdentifier interface {
// GetMessageID returns message identifier of given API message.
GetMessageID(msg Message) (uint16, error)
// LookupByID looks up message name and crc by ID
LookupByID(ID uint16) (string, error)
}
// Channel provides methods for direct communication with VPP channel.
type Channel interface {
// SendRequest asynchronously sends a request to VPP. Returns a request context, that can be used to call ReceiveReply.
// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
SendRequest(msg Message) RequestCtx
// SendMultiRequest asynchronously sends a multipart request (request to which multiple responses are expected) to VPP.
// Returns a multipart request context, that can be used to call ReceiveReply.
// In case of any errors by sending, the error will be delivered to ReplyChan (and returned by ReceiveReply).
SendMultiRequest(msg Message) MultiRequestCtx
// SubscribeNotification subscribes for receiving of the specified notification messages via provided Go channel.
// Note that the caller is responsible for creating the Go channel with preferred buffer size. If the channel's
// buffer is full, the notifications will not be delivered into it.
SubscribeNotification(notifChan chan Message, msgFactory func() Message) (*NotifSubscription, error)
// UnsubscribeNotification unsubscribes from receiving the notifications tied to the provided notification subscription.
UnsubscribeNotification(subscription *NotifSubscription) error
// CheckMessageCompatibility checks whether provided messages are compatible with the version of VPP
// which the library is connected to.
CheckMessageCompatibility(messages ...Message) error
// SetReplyTimeout sets the timeout for replies from VPP. It represents the maximum time the API waits for a reply
// from VPP before returning an error.
SetReplyTimeout(timeout time.Duration)
// GetRequestChannel returns request go channel of the VPP channel
GetRequestChannel() chan<- *VppRequest
// GetReplyChannel returns reply go channel of the VPP channel
GetReplyChannel() <-chan *VppReply
// GetNotificationChannel returns notification go channel of the VPP channel
GetNotificationChannel() chan<- *NotifSubscribeRequest
// GetNotificationReplyChannel returns notification reply go channel of the VPP channel
GetNotificationReplyChannel() <-chan error
// GetMessageDecoder returns message decoder instance
GetMessageDecoder() MessageDecoder
// GetID returns channel's ID
GetID() uint16
// Close closes the API channel and releases all API channel-related resources in the ChannelProvider.
Close()
}
// RequestCtx is helper interface which allows to receive reply on request context data
type RequestCtx interface {
// ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs).
// The reply will be decoded into the msg argument. Error will be returned if the response cannot be received or decoded.
ReceiveReply(msg Message) error
}
// MultiRequestCtx is helper interface which allows to receive reply on multi-request context data
type MultiRequestCtx interface {
// ReceiveReply receives a reply from VPP (blocks until a reply is delivered from VPP, or until an error occurs).
// The reply will be decoded into the msg argument. If the last reply has been already consumed, lastReplyReceived is
// set to true. Do not use the message itself if lastReplyReceived is true - it won't be filled with actual data.
// Error will be returned if the response cannot be received or decoded.
ReceiveReply(msg Message) (lastReplyReceived bool, err error)
}
// VppRequest is a request that will be sent to VPP.
type VppRequest struct {
SeqNum uint16 // sequence number
Message Message // binary API message to be send to VPP
Multipart bool // true if multipart response is expected, false otherwise
}
// VppReply is a reply received from VPP.
type VppReply struct {
MessageID uint16 // ID of the message
SeqNum uint16 // sequence number
Data []byte // encoded data with the message - MessageDecoder can be used for decoding
LastReplyReceived bool // in case of multipart replies, true if the last reply has been already received and this one should be ignored
Error error // in case of error, data is nil and this member contains error description
}
// NotifSubscribeRequest is a request to subscribe for delivery of specific notification messages.
type NotifSubscribeRequest struct {
Subscription *NotifSubscription // subscription details
Subscribe bool // true if this is a request to subscribe, false if unsubscribe
}
// NotifSubscription represents a subscription for delivery of specific notification messages.
type NotifSubscription struct {
NotifChan chan Message // channel where notification messages will be delivered to
MsgFactory func() Message // function that returns a new instance of the specific message that is expected as a notification
}
|
