1 // Package api provides API for communication with govpp core using Go channels,
2 // without the need of importing the govpp core package itself.
4 // The API offers two ways of communication with govpp core: using Go channels, or using convenient function
5 // wrappers over the Go channels. The latter should be sufficient for most of the use cases.
7 // The entry point to the API is the Channel structure, that can be obtained from the existing connection using
8 // the NewAPIChannel or NewAPIChannelBuffered functions:
10 // conn, err := govpp.Connect()
14 // defer conn.Disconnect()
16 // ch, err := conn.NewAPIChannel()
23 // Simple Request-Reply API
25 // The simple version of the API is based on blocking SendRequest / ReceiveReply calls, where a single request
26 // message is sent to VPP and a single reply message is filled in when the reply comes from VPP:
28 // req := &acl.ACLPluginGetVersion{}
29 // reply := &acl.ACLPluginGetVersionReply{}
31 // err := ch.SendRequest(req).ReceiveReply(reply)
32 // // process the reply
34 // Note that if the reply message type that comes from VPP does not match with provided one, you'll get an error.
37 // Multipart Reply API
39 // If multiple messages are expected as a reply to a request, SendMultiRequest API must be used:
41 // req := &interfaces.SwInterfaceDump{}
42 // reqCtx := ch.SendMultiRequest(req)
45 // reply := &interfaces.SwInterfaceDetails{}
46 // stop, err := reqCtx.ReceiveReply(reply)
48 // break // break out of the loop
50 // // process the reply
53 // Note that if the last reply has been already consumed, stop boolean return value is set to true.
54 // Do not use the message itself if stop is true - it won't be filled with actual data.
59 // The blocking API introduced above may be not sufficient for some management applications that strongly
60 // rely on usage of Go channels. In this case, the API allows to access the underlying Go channels directly, e.g.
61 // the following replacement of the SendRequest / ReceiveReply API:
63 // req := &acl.ACLPluginGetVersion{}
64 // // send the request to the request go channel
65 // ch.ReqChan <- &api.VppRequest{Message: req}
67 // // receive a reply from the reply go channel
68 // vppReply := <-ch.ReplyChan
70 // // decode the message
71 // reply := &acl.ACLPluginGetVersionReply{}
72 // err := ch.MsgDecoder.DecodeMsg(vppReply.Data, reply)
74 // // process the reply
79 // to subscribe for receiving of the specified notification messages via provided Go channel, use the
80 // SubscribeNotification API:
82 // // subscribe for specific notification message
83 // notifChan := make(chan api.Message, 100)
84 // subs, _ := ch.SubscribeNotification(notifChan, interfaces.NewSwInterfaceSetFlags)
86 // // receive one notification
87 // notif := (<-notifChan).(*interfaces.SwInterfaceSetFlags)
89 // ch.UnsubscribeNotification(subs)
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.