# os_ken.app.ofctl

os_ken.app.ofctl provides a convenient way to use OpenFlow messages synchronously.

OfctlService os_ken application is automatically loaded if your OS-Ken application imports ofctl.api module.

Example:

    import os_ken.app.ofctl.api

OfctlService application internally uses OpenFlow barrier messages to ensure message boundaries. As OpenFlow messages are asynchronous and some of messages does not have any replies on success, barriers are necessary for correct error handling.

## api module

os_ken.app.ofctl.api.get_datapath(app, dpid=None)

  Get datapath object by dpid.

  Parameters:

    - app -- Client OSKenApp instance

    - dpid -- Datapath ID (int type) or None to get all datapath objects

  Returns a object of datapath, a list of datapath objects when no dpid given or None when error.

  Raises an exception if any of the given values is invalid.

  Example:

      # ...(snip)...
      import os_ken.app.ofctl.api as ofctl_api

      class MyApp(app_manager.OSKenApp):

          def _my_handler(self, ev):
              # Get all datapath objects
              result = ofctl_api.get_datapath(self)

              # Get the datapath object which has the given dpid
              result = ofctl_api.get_datapath(self, dpid=1)

os_ken.app.ofctl.api.send_msg(app, msg, reply_cls=None, reply_multi=False)

  Send an OpenFlow message and wait for reply messages.

  Parameters:

    - app -- Client OSKenApp instance

    - msg -- An OpenFlow controller-to-switch message to send

    - reply_cls -- OpenFlow message class for expected replies. None means no replies are expected. The default is None.

    - reply_multi -- True if multipart replies are expected. The default is False.

  If no replies, returns None. If reply_multi=False, returns OpenFlow switch-to-controller message. If reply_multi=True, returns a list of OpenFlow switch-to-controller messages.

  Raise an exception on error.

  Example:

      # ...(snip)...
      import os_ken.app.ofctl.api as ofctl_api

      class MyApp(app_manager.OSKenApp):

          def _my_handler(self, ev):
              # ...(snip)...
              msg = parser.OFPPortDescStatsRequest(datapath=datapath)
              result = ofctl_api.send_msg(
                  self, msg,
                  reply_cls=parser.OFPPortDescStatsReply,
                  reply_multi=True)

## exceptions

exception os_ken.app.ofctl.exception.InvalidDatapath(result)

  Datapath is invalid.

  This can happen when the bridge disconnects.

exception os_ken.app.ofctl.exception.OFError(result)

  OFPErrorMsg is received.

exception os_ken.app.ofctl.exception.UnexpectedMultiReply(result)

  Two or more replies are received for reply_muiti=False request.

this page last updated: 2026-04-10 03:11:34

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug