From 9f3139c5c31ed9e2cfe4ee414893ab6948f86736 Mon Sep 17 00:00:00 2001
From: winlin <winlin@vip.126.com>
Date: Sun, 8 Dec 2013 09:22:33 +0800
Subject: [PATCH] add comments for api server

---
 trunk/research/api-server/server.py | 46 +++++++++++++++++++----------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/trunk/research/api-server/server.py b/trunk/research/api-server/server.py
index 435bdc0d3..46f28b69c 100755
--- a/trunk/research/api-server/server.py
+++ b/trunk/research/api-server/server.py
@@ -36,25 +36,14 @@ reload(sys);
 exec("sys.setdefaultencoding('utf-8')");
 assert sys.getdefaultencoding().lower() == "utf-8";
 
-if __name__ != "__main__":
-    raise Exception("embed not support");
-
-if len(sys.argv) <= 1:
-    print "SRS api callback server, Copyright (c) 2013 winlin"
-    print "Usage: python %s <port>"%(sys.argv[0])
-    print "    port: the port to listen at."
-    print "For example:"
-    print "    python %s 8085"%(sys.argv[0])
-    print ""
-    print "See also: https://github.com/winlinvip/simple-rtmp-server"
-    sys.exit(1)
-
 import json, datetime, cherrypy
 
+# simple log functions.
 def trace(msg):
     date = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
     print "[%s][trace] %s"%(date, msg)
 
+# enable crossdomain access for js-client
 def enable_crossdomain():
     cherrypy.response.headers["Access-Control-Allow-Origin"] = "*"
     cherrypy.response.headers["Access-Control-Allow-Methods"] = "GET, POST, HEAD, PUT, DELETE"
@@ -62,6 +51,7 @@ def enable_crossdomain():
     allow_headers = ["Cache-Control", "X-Proxy-Authorization", "X-Requested-With", "Content-Type"]
     cherrypy.response.headers["Access-Control-Allow-Headers"] = ",".join(allow_headers)
 
+# error codes definition
 class Error:
     # ok, success, completed.
     success = 0
@@ -74,12 +64,14 @@ POST: create new client, handle the SRS on_connect callback.
 '''
 class RESTClients(object):
     exposed = True
+
     def GET(self):
         enable_crossdomain();
 
         clients = {};
         return json.dumps(clients);
 
+    # for SRS hook: on_connect
     def POST(self):
         enable_crossdomain();
 
@@ -97,21 +89,43 @@ class RESTClients(object):
     def OPTIONS(self):
         enable_crossdomain()
 
+# HTTP RESTful path.
 class Root(object):
     def __init__(self):
         self.api = Api()
-
+# HTTP RESTful path.
 class Api(object):
     def __init__(self):
         self.v1 = V1()
-
+# HTTP RESTful path. to access as:
+#   http://127.0.0.1:8085/api/v1/clients
 class V1(object):
     def __init__(self):
         self.clients = RESTClients()
 
+'''
+main code start.
+'''
+# donot support use this module as library.
+if __name__ != "__main__":
+    raise Exception("embed not support");
+
+# check the user options
+if len(sys.argv) <= 1:
+    print "SRS api callback server, Copyright (c) 2013 winlin"
+    print "Usage: python %s <port>"%(sys.argv[0])
+    print "    port: the port to listen at."
+    print "For example:"
+    print "    python %s 8085"%(sys.argv[0])
+    print ""
+    print "See also: https://github.com/winlinvip/simple-rtmp-server"
+    sys.exit(1)
+
+# parse port from user options.
 port = int(sys.argv[1])
 trace("api server listen at port: %s"%(port))
 
+# cherrypy config.
 conf = {
     'global': {
         'server.shutdown_timeout': 1,
@@ -121,9 +135,11 @@ conf = {
         'tools.encode.encoding': "utf-8"
     },
     '/': {
+        # for cherrypy RESTful api support
         'request.dispatch': cherrypy.dispatch.MethodDispatcher()
     }
 }
 
+# start cherrypy web engine
 trace("start cherrypy server")
 cherrypy.quickstart(Root(), '/', conf)