document ryu.app.ofctl

Signed-off-by: YAMAMOTO Takashi <yamamoto@valinux.co.jp>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

5 files changed, 75 insertions, 1 deletions

diff --git a/doc/source/app.rst b/doc/source/app.rst
new file mode 100644
index 00000000..c20b0bf0
--- /dev/null
+++ b/doc/source/app.rst
@@ -0,0 +1,12 @@
+*************************
+Built-in Ryu applications
+*************************
+
+Ryu has some built-in Ryu applications.
+Some of them are examples.
+Others provide some functionalities to other Ryu applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   app/ofctl.rst
diff --git a/doc/source/app/ofctl.rst b/doc/source/app/ofctl.rst
new file mode 100644
index 00000000..b293f342
--- /dev/null
+++ b/doc/source/app/ofctl.rst
@@ -0,0 +1,30 @@
+*************
+ryu.app.ofctl
+*************
+
+ryu.app.ofctl provides a convenient way to use OpenFlow messages
+synchronously.
+
+OfctlService ryu application is automatically loaded if your
+Ryu application imports ofctl.api module.
+
+Example::
+
+    import ryu.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
+==========
+
+.. automodule:: ryu.app.ofctl.api
+   :members:
+
+exceptions
+==========
+
+.. automodule:: ryu.app.ofctl.exception
+   :members:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c9a0cb46..cfe256b8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -17,6 +17,7 @@ Contents:
    configuration.rst
    tests.rst
    using_with_openstack.rst
+   app.rst
 
 Indices and tables
 ==================
diff --git a/ryu/app/ofctl/api.py b/ryu/app/ofctl/api.py
index 64f06f0a..8a62125a 100644
--- a/ryu/app/ofctl/api.py
+++ b/ryu/app/ofctl/api.py
@@ -23,6 +23,10 @@ import event
 def get_datapath(app, dpid):
     """
     Get datapath object by dpid.
+
+    :param app: Client RyuApp instance
+    :param dpid: Datapath-id (in integer)
+
     Returns None on error.
     """
     assert isinstance(dpid, (int, long))
@@ -31,7 +35,30 @@ def get_datapath(app, dpid):
 
 def send_msg(app, msg, reply_cls=None, reply_multi=False):
     """
-    Send an openflow message.
+    Send an OpenFlow message and wait for reply messages.
+
+    :param app: Client RyuApp instance
+    :param msg: An OpenFlow controller-to-switch message to send
+    :param reply_cls: OpenFlow message class for expected replies.
+        None means no replies are expected.  The default is None.
+    :param 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::
+
+        import ryu.app.ofctl.api as api
+
+        msg = parser.OFPPortDescStatsRequest(datapath=datapath)
+        result = api.send_msg(self, msg,
+                                    reply_cls=parser.OFPPortDescStatsReply,
+                                    reply_multi=True)
     """
     return app.send_request(event.SendMsgRequest(msg=msg,
                                                  reply_cls=reply_cls,
diff --git a/ryu/app/ofctl/exception.py b/ryu/app/ofctl/exception.py
index c49f33f2..01557488 100644
--- a/ryu/app/ofctl/exception.py
+++ b/ryu/app/ofctl/exception.py
@@ -26,8 +26,12 @@ class _ExceptionBase(exception.RyuException):
 
 
 class UnexpectedMultiReply(_ExceptionBase):
+    """Two or more replies are received for reply_muiti=False request."""
+
     message = 'Unexpected Multi replies %(result)s'
 
 
 class OFError(_ExceptionBase):
+    """OFPErrorMsg is received."""
+
     message = 'OpenFlow errors %(result)s'