-// Copyright (c) 2017 Cisco and/or its affiliates.
+// Copyright (c) 2020 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:
+// 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
+// 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.
+// 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 (
- "fmt"
+ "context"
"time"
)
-// MessageType represents the type of a VPP message.
-// Note: this is currently derived from the message header (fields),
-// and in many cases it does not represent the actual type of VPP message.
-// This means that some replies can be identified as requests, etc.
-// TODO: use services to identify type of 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 event message
- EventMessage
- // OtherMessage represents other VPP message
- 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
-
- // GetCrcString returns the string with CRC checksum of the message definition (the string represents a hexadecimal number).
- GetCrcString() string
-
- // GetMessageType returns the type of the VPP message.
- GetMessageType() MessageType
-}
-
-// 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
-}
-
-// 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
+// Connection represents the client connection to VPP API.
+//
+// NOTE: This API is EXPERIMENTAL.
+type Connection interface {
+ // NewStream creates a new stream for sending and receiving messages.
+ // Context can be used to close the stream using cancel or timeout.
+ NewStream(ctx context.Context) (Stream, error)
+
+ // Invoke can be used for a simple request-reply RPC.
+ // It creates stream and calls SendMsg with req and RecvMsg with reply.
+ Invoke(ctx context.Context, req Message, reply 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(msgID uint16) (Message, error)
+// Stream provides low-level access for sending and receiving messages.
+// Users should handle correct type and ordering of messages.
+//
+// NOTE: This API is EXPERIMENTAL.
+type Stream interface {
+ // SendMsg sends a message to the client.
+ // It blocks until message is sent to the transport.
+ //
+ // It is safe to have a goroutine calling SendMsg and another goroutine
+ // calling RecvMsg on the same stream at the same time, but it is not safe
+ // to call SendMsg on the same stream in different goroutines.
+ SendMsg(Message) error
+
+ // RecvMsg blocks until a message is received or error occurs.
+ //
+ // It is safe to have a goroutine calling SendMsg and another goroutine
+ // calling RecvMsg on the same stream at the same time, but it is not safe
+ // to call SendMsg on the same stream in different goroutines.
+ RecvMsg() (Message, error)
+
+ // Close closes the stream. Calling SendMsg and RecvMsg will return error
+ // after closing stream.
+ Close() error
}
// ChannelProvider provides the communication channel with govpp core.
// Channel provides methods for direct communication with VPP channel.
type Channel interface {
- // GetID returns channel's ID
- GetID() uint16
-
// 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
// 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
+ SubscribeNotification(notifChan chan Message, event Message) (SubscriptionCtx, 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)
- // Close closes the API channel and releases all API channel-related resources in the ChannelProvider.
+ // CheckCompatibility checks the compatiblity for the given messages.
+ // It will return an error if any of the given messages are not compatible.
+ CheckCompatiblity(msgs ...Message) error
+
+ // 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
+// RequestCtx is helper interface which allows to receive reply on request.
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 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
+// MultiRequestCtx is helper interface which allows to receive reply on multi-request.
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 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)
}
-// 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
- // TODO: use Message directly here, not a factory, eliminating need to allocation
-}
-
-var registeredMessages = make(map[string]Message)
-
-// RegisterMessage is called from generated code to register message.
-func RegisterMessage(x Message, name string) {
- if _, ok := registeredMessages[name]; ok {
- panic(fmt.Errorf("govpp: duplicate message registered: %s (%s)", name, x.GetCrcString()))
- }
- registeredMessages[name] = x
-}
-
-// GetAllMessages returns list of all registered messages.
-func GetAllMessages() map[string]Message {
- return registeredMessages
+// SubscriptionCtx is helper interface which allows to control subscription for
+// notification events.
+type SubscriptionCtx interface {
+ // Unsubscribe unsubscribes from receiving the notifications tied to the
+ // subscription context.
+ Unsubscribe() error
}