KBEngine Module
The KBEngine module mainly handles the integration and disconnection between the KBEngine server and third-party platforms.
Member Functions
def addTimer( initialOffset, repeatOffset=0, callbackObj=None ):
def accountLoginResponse( commitName, realAccountName, extraDatas, errorCode ):
def createAccountResponse( commitName, realAccountName, extraDatas, errorCode ):
def chargeResponse( orderID, extraDatas, errorCode ):
def delTimer( id ):
def executeRawDatabaseCommand( command, callback, threadID, dbInterfaceName ):
def urlopen( url, callback, postData, headers ):
Callback Functions
def onInterfaceAppReady( ):
def onInterfaceAppShutDown( ):
def onRequestCreateAccount( registerName, password, datas ):
def onRequestAccountLogin( loginName, password, datas ):
def onRequestCharge( ordersID, entityDBID, datas ):
Member Function Documentation
def addTimer( initialOffset, repeatOffset=0, callbackObj=None ):
Description:
Registers a timer, which is triggered by the callback function callbackObj. The callback function will be executed for the first time after "initialOffset" seconds, and then every "repeatOffset" seconds.
Example:
# Example of using addTimer
import KBEngine
# Add a timer, execute for the first time after 5 seconds, then every 1 second, user parameter is 9
KBEngine.addTimer( 5, 1, onTimer_Callbackfun )
# Add a timer, execute after 1 second, user parameter defaults to 0
KBEngine.addTimer( 1, onTimer_Callbackfun )
def onTimer_Callbackfun( id ):
print("onTimer_Callbackfun called: id %i" % ( id ))
# if this is a repeating timer, when it is no longer needed, call the following function to remove it:
# KBEngine.delTimer( id )Parameters:
initialOffset: float, the interval (seconds) from registration to the first callback.
repeatOffset: float, the interval (seconds) between each execution after the first callback. Must be removed with delTimer, otherwise it will repeat indefinitely. Values less than or equal to 0 will be ignored.
callbackObj: function, the specified callback function object.
Returns:
integer, returns the internal id of the timer, which can be used to remove the timer with delTimer.
def accountLoginResponse( commitName, realAccountName, extraDatas, errorCode ):
Description:
After onRequestAccountLogin is called back, the script needs to call this interface to provide the login processing result.
Parameters:
commitName: string, the name submitted by the client request.
realAccountName: string, returns the real account name (usually the same as commitName, can be used for various alias logins).
extraDatas: bytes, data attached by the client request, can be forwarded to third-party platforms, and can be modified here. This parameter can be read in the script via the base entity's getClientDatas interface.
errorCode: integer, error code. If you need to interrupt the user's action, you can set the error code here. Error codes can refer to (KBEngine.SERVER_ERROR_*, described in kbengine/kbe/res/server/server_errors.xml), otherwise submit KBEngine.SERVER_SUCCESS to allow login.
def createAccountResponse( commitName, realAccountName, extraDatas, errorCode ):
Description:
After onRequestCreateAccount is called back, the script needs to call this interface to provide the account creation processing result.
Parameters:
commitName: string, the name submitted by the client request.
realAccountName: string, returns the real account name (usually the same as commitName, can be used for various alias logins).
extraDatas: bytes, data attached by the client request, can be forwarded to third-party platforms, and can be modified here. This parameter can be read in the script via the base entity's getClientDatas interface.
errorCode: integer, error code. If you need to interrupt the user's action, you can set the error code here. Error codes can refer to (KBEngine.SERVER_ERROR_*, described in kbengine/kbe/res/server/server_errors.xml), otherwise submit KBEngine.SERVER_SUCCESS to allow login.
def chargeResponse( orderID, extraDatas, errorCode ):
Description:
After onRequestCharge is called back, the script needs to call this interface to provide the billing processing result.
Parameters:
ordersID: string, the order ID.
extraDatas: bytes, data attached by the client request, can be forwarded to third-party platforms, and can be modified here. This parameter can be read in the script via the base entity's getClientDatas interface.
errorCode: integer, error code. If you need to interrupt the user's action, you can set the error code here. Error codes can refer to (KBEngine.SERVER_ERROR_*, described in kbengine/kbe/res/server/server_errors.xml), otherwise submit KBEngine.SERVER_SUCCESS to allow login.
def delTimer( id ):
Description:
The delTimer function is used to remove a registered timer. The removed timer will no longer execute. Timers that only execute once are automatically removed after the callback, so there is no need to remove them with delTimer. If delTimer is called with an invalid id (e.g., already removed), an error will occur.
See KBEngine.addTimer for an example of using timers.
Parameters:
id: integer, specifies the timer id to remove.
def executeRawDatabaseCommand( command, callback, threadID, dbInterfaceName ):
Description:
This script function executes a raw database command on the database, which will be parsed directly by the relevant database.
Please note that modifying entity data with this function may not take effect, because if the entity has been checked out, the modified entity data will still be overwritten by the entity archive.
It is strongly discouraged to use this function to read or modify entity data.
Parameters:
command: This database command will vary depending on the database configuration. For MySQL, it is an SQL query statement.
callback: Optional parameter, a callback object (such as a function) with the result of the command execution. This callback takes 4 parameters: result set, affected rows, insert id, error message.
Example Declaration
def sqlcallback(result, rows, insertid, error):
print(result, rows, insertid, error)As shown above:
result corresponds to the "result set", which is a list of rows. Each row is a list of string field values.
If the command does not return a result set (e.g., DELETE command), or if there is an error, this result set is None.
rows is the "number of affected rows", an integer indicating the number of rows affected by the command. This parameter is only relevant for commands that do not return a result set (such as DELETE).
If there is a result set or an error, this parameter is None.
insertid is the "auto-increment value", similar to the entity's databaseID. When data is successfully inserted into a table with an auto-increment field, it returns the value assigned to the auto-increment field at insertion. For more information, see MySQL's mysql_insert_id() method. This parameter is only meaningful when the database type is MySQL.
error is the "error message". If there is an error, this parameter is a string describing the error. If there is no error, this parameter is None.
threadID: int32, optional parameter, specifies a thread to handle this command. You can use this parameter to control the execution order of certain commands (dbmgr is multi-threaded). By default, it is not specified. If threadID is the entity's ID, it will be added to the entity's archive queue and written sequentially by the thread.
dbInterfaceName: string, optional parameter, specifies which database interface to use, defaults to the "default" interface. Database interfaces are defined in kbengine_defaults.xml->dbmgr->databaseInterfaces.
def urlopen( url, callback, postData, headers ):
Description:
This script function provides asynchronous HTTP/HTTPS requests.
Parameters:
url: A valid HTTP/HTTPS URL, string type.
callback: Optional parameter, a callback object (such as a function) with the result of the request. This callback takes 5 parameters: HTTP response code (e.g., 200), response content, HTTP headers, success status, and the request URL.
Example Declaration:
def onHttpCallback(httpcode, data, headers, success, url):
print(httpcode, data, headers, success, url)As shown above:
httpcode: The HTTP response code, an integer value.
data: The response content, a string.
headers: The HTTP headers returned by the server, e.g., {"Content-Type": "application/x-www-form-urlencoded"}, a dictionary.
success: Whether the request was successful. If there was an error, this is False. You can use httpcode to further determine the error.
url: The URL used for the request.
postData: Optional parameter. By default, a GET request is made to the server. If you need a POST request, provide the content to POST, and the engine will automatically use POST. It is bytes.
headers: Optional parameter. The HTTP headers to use for the request, e.g., {"Content-Type": "application/x-www-form-urlencoded"}, a dictionary.
Callback Function Documentation
def onInterfaceAppReady( ):
Description:
This function is called when the current process is ready.
Note: This callback must be implemented in the entry module (kbengine_defaults.xml->entryScriptFile).
def onInterfaceAppShutDown( ):
Description:
This function is called when the process is shutting down.
Note: This callback must be implemented in the entry module (kbengine_defaults.xml->entryScriptFile).
def onRequestCreateAccount( registerName, password, datas ):
Description:
This callback is called when the client requests to create an account on the server.
You can check and modify the data in this function, and submit the final result to the engine via KBEngine.createAccountResponse.
Note: This callback must be implemented in the entry module (kbengine_defaults.xml->entryScriptFile).
Parameters:
registerName: string, the name submitted by the client request.
password: string, password.
datas: bytes, data attached by the client request, can be forwarded to third-party platforms.
def onRequestAccountLogin( loginName, password, datas ):
Description:
This callback is called when the client requests to log in to an account on the server.
You can check and modify the data in this function, and submit the final result to the engine via KBEngine.accountLoginResponse.
Note: This callback must be implemented in the entry module (kbengine_defaults.xml->entryScriptFile).
Parameters:
loginName: string, the name submitted by the client request.
password: string, password.
datas: bytes, data attached by the client request, can be forwarded to third-party platforms.
def onRequestCharge( ordersID, entityDBID, datas ):
Description:
This callback is called when a billing request is made (usually when KBEngine.charge is called on baseapp).
You can check and modify the data in this function, and submit the final result to the engine via KBEngine.chargeResponse.
Note: This callback must be implemented in the entry module (kbengine_defaults.xml->entryScriptFile).
Parameters:
ordersID: uint64, the order ID.
entityDBID: uint64, the DBID of the entity submitting the order.
datas: bytes, data attached by the client request, can be forwarded to third-party platforms.