webservice_wrapper

NPL remote web service call wrapper with a pre function and post function.

Title	NPL remote web service call wrapper with a pre function and post function.
Author(s)	LiXizhi
Date	2008/1/21
File	script/kids/3DMapSystemApp/API/webservice_wrapper.lua

Description

Sample Code

NPL.load("(gl)script/kids/3DMapSystemApp/API/webservice_wrapper.lua");
paraworld.CreateRPCWrapper(fullname, url, prepFunc, postFunc)
-- see paraworld.* files for more examples. 

Member Functions

paraworld.CreateRPCWrapper

---

web service wrapper functions

---

[[ Create an rpc wrapper function using closures. it will override existing one with identical name.

• param fullName : by which name we name the RPC, it should contains at least one namespace. such as "paraworld.auth.AuthUser"
• param url : url of the RPC path, such as "http://auth.paraengine.com/AuthUser.asmx"
• param prepFunc : nil or an input message validation function (self, msg, id, callbackFunc, callbackParams) end the function is called before making the RPC call to validate the input msg and preconditions. e.g. If user is not logged in, it will open a login window for user authentication. the function should return nil if should continue with web service call, otherwise either true or a paraworld.errorcode is returned. If there is an error in preprocessing, the user callback is not called. and the error code is returned immediately from the rpc wrapper function. One can create custom preprocessorFunc for each RPC wrapper, or use one of the predefined processor. Another usage of prepFunc is that it can secretly translate input message to whatever the remote format message is.
• param postFunc : nil or an output message validation function (self, msg, id) end the function is called after the RPC returns to validate the output msg and then send the result to the user callback. e.g. It may report and handle certain common error, such as sesssion key expirations, etc. the function should return nil if successful, otherwise a paraworld.errorcode is returned. whether there is error or not the user callback is always called.
• Note by : LiXizhi: all resource of the rpc is kept in a closure and there is only one global table "fullname" created. I overwrite the table's __call method to make it callable with ease. -- For example: after calling paraworld.CreateRPCWrapper("paraworld.auth.AuthUser", "http://auth.paraengine.com/AuthUser.asmx"); -- we can call the rpc via wrapper paraworld.auth.AuthUser like this paraworld.auth.AuthUser({Username="", Password=""}, "test", function (msg, params) log(commonlib.serialize(msg)) end, "ABC"); -- The above call is identical to paraworld.auth.AuthUser:activate(...); -- The url of the web service can be get/set via local url = paraworld.auth.AuthUser.GetUrl() paraworld.auth.AuthUser.SetUrl("anything here") -- tostring() can also be used like this log(tostring(paraworld.auth.AuthUser).."\n")
• example code : see "script/kids/3DMapSystemApp/API/test/paraworld.auth.test.lua"

]]

syntax

function paraworld.CreateRPCWrapper(fullname, url, prepFunc, postFunc)

parameters

fullname
url

| prepFunc | nil or an input message validation function (self, msg, id, callbackFunc, callbackParams) end the function is called before making the RPC call to validate the input msg and preconditions. e.g. If user is not logged in, it will open a login window for user authentication. the function should return nil if should continue with web service call, otherwise either true or a paraworld.errorcode is returned. If there is an error in preprocessing, the user callback is not called. and the error code is returned immediately from the rpc wrapper function. One can create custom preprocessorFunc for each RPC wrapper, or use one of the predefined processor. Another usage of prepFunc is that it can secretly translate input message to whatever the remote format message is. |

postFunc

paraworld.ShowMessage

---

helper functions

---

show a status message.

syntax

function paraworld.ShowMessage(text,...)

parameters

text

paraworld.check_result

return whether the result msg is a success. optionally, it can report most error messages via standard popup dialog. it will check msg, msg.isSuccess, msg.info and msg.errorCode

• param msg : the message
• param bShowErrorToUser : if true, it will show error message to user via standard popup dialog.
• return __ : bSuccess, errormsg: return true if msg is a general success, or nil if otherwise. and the second return parameter contains the translated errormsg.

syntax

function paraworld.check_result(msg, bShowErrorToUser)

parameters

msg	the message
bShowErrorToUser
return	bSuccess, errormsg: return true if msg is a general success, or nil if otherwise. and the second return parameter contains the translated errormsg.

paraworld.prepLoginRequried

---

predefined preprocessor and postprocessor functions

---

if the current user is not authenticated, it will return paraworld.errorcode.LoginRequired. and display the login dialog if the current user is authenticated, it will add the sessionKey and userId to the msg.

syntax

function paraworld.prepLoginRequried(self, msg, id, callbackFunc, callbackParams)

parameters

self
msg
id
callbackFunc
callbackParams

paraworld.IsAuthenticated

whether the current user is authenticated.

syntax

function paraworld.IsAuthenticated()