api/api.go

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