|
|
This document will show how you can implement your own callback function for the callback points provided by the WebsydianExpress runtime.
The callback functions offers the possibility to add custom functionality to the functionality performed by the WebsydianExpress runtime in specific situations.
The document also contains a short description of each of these callback points.
For each callback point you can specify any number of callback functions.
Note that this document describes how you can implement callback functions for RPG Developer for WebsydianExpress. If you want to implement callback functions in Plex, go to this document instead:
Create a ILE RPG function that includes the EXPRESS_H header:
D/COPY *libl/QRPGLESRC,EXPRESS_H
The interface of the function must be a 7 character return code - for example:
Online documentation - WebsydianExpress v3.0
D ReturnCode S 7A
C *ENTRY PLIST
C parm ReturnCode
As the callback functions are called dynamically by the runtime, you can't specify any parameters additional parameters for the function.
But there is still some of the callback points that transfers information for the callback functions. This information can be retrieved by calling the API CallbackInputGet.
When calling this function you must specify the name of the parameter to get. For each parameter used by the system defined callback points, constants has been specified in the WICALB_H header file - the description for each callback point found below specifies which parameters you can retrieve.
For some of the callback functions there is also the option to return some information. You make this information available for the calling function by calling the API CallbackOuputSet.
As for the CallbackInputGet function, you must provide the name of the field together with the value - information about which information you can set is of course also found in the description of the callback points found below.
After implementing your custom functionality and compiling the function, you must specify that the function should be called for the callback point. This is done using the administration interface menu item Callback functions.
No input or output parameters.
ApplicationServiceEnd is called when the Application Service exists.
None.
Used to perform clean-up processing that must be done before the Application Service exits.
If you have used the ApplicationServiceStart callback point to connect/logon to a back-end system (e.g. an ERP system), you need want to disconnect from/log off this system.
ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.
No input or output parameters.
ApplicationServiceStart is called when the Application Service starts.
None.
Used to allocate resources that should be used by the Application Service and are shared by all requests; e.g. connection to back-end systems (for example ERP systems).
ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.
| Field | Type | Constant | Description |
|---|---|---|---|
| ContinueHandling | Output | CB_CONTINUE | Specifies whether the request should be handled by the Websydian Runtime |
Call the API CallbackOutputSet to return the information to the calling function.
BeforeRequestStart is called after the request has been received by the runtime, but before any handling of the request has been performed.
Setting the output parameter to Yes will let the normal handling proceed.
Setting the output parameter to No will stop all handling of the request.
This means that the callback function offers the possibility to take full control of the handling of a request.
Please note that this includes all handling - including calling a PageGenerator function if you want anything to be sent to the browser.
You must also note that the request has not been parsed or in any way interpreted by this function. If you do need to use this function contact websydian support with a description of your case to obtain information about how you can retrieve the relevant request headers and the request body.
The case for this callback function was an installation, where it also was necessary to be able to process web service requests.
By checking the content type header it was possible to find the requests that contained xml - and to let the function call a service function that was specially designed to handle the web service requests. After calling the service function that handled the web service request, the ContinueHandling flag was set to No to prevent the normal handling of the request.
No input or output parameters.
HandlingRequestStart is called when a request is received and the request parameter string has been parsed and written to memory.
None.
At this point, you can use the GetInput API to retrieve information about the parameters specified on the request.
ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.
No input or output parameters.
HandlingRequestEnd is called when the processing of a request is ended.
None.
Used to perform any clean-up processing that must be done at the end of a request.
ApplicationServiceStart, ApplicationServiceEnd, HandlingRequestStart, and HandlingRequestEnd can be used together to write log information about the system to a file.
| Field | Type | Condition | Description |
|---|---|---|---|
| Session ID | Input | CB_SESSIONID | The unique identifier for the session. |
| IPIntranetMask | Input | CB_INTRAMASK | The IP intranet mask specified on site settings. |
| IsIPInIntranet | Input | CB_IPINTRANET | The current setting of the Flag determining if the session is in the intranet. |
| IsIPInIntranet | Output | CB_IPINTRANET | Set to Y if the IP address on the session belongs to the specified IP intranet mask. Set to N otherwise. |
Use the API CallbackGetInput to retrieve the input parameters and the API CallbackOutputSet to return the output parameter to the calling function.
The functions is called when a session is created in order to determine whether a session belongs to the Intranet or the Extranet.
The function is called immediately after the runtime has determined whether the session is in the intranet based on the intranet mask specified in the site settings.
Based on the value of the field IsIPInIntranet the assignment of roles to the session will be affected.
The IP intranet mask in WebsydianExpress is specified as a partial IP address, e.g. "192.168.".
In more complex network environments it could be necessary to specify a more advanced IP mask. E.g. like "192.168.0.0/255.254.0.0". In this case it will be necessary to implement this callback function and check whether the IP address on the session belongs to the specified IP mask.
As for all the callback points, several callback functions can be defined for the IsSessionInIntranet callback point. This means that there is the possibility that the one runtime has determined that the session is not in the intranet, one callback function has determined that the session is in the intranet and yet another function has determined that it is not in the intranet (all based on the rules implemented by the callback functions). In all these cases, the output last callback function determines whether the session will be handled as being in the intranet.
To make it possible for the callback function to take the results of the runtime and any previously called callback functions for the callback point into consideration, the current state of the IsIPInIntranet is transferred as an input parameter to the callback function. It is up to the developer to determine whether he will take this value into account.
You can specify the sequence in which the callback functions will be called using the administration interface menu item callback functions.
| Field | Type | Condition | Description |
|---|---|---|---|
| Session ID | Input | CB_SESSIONID | The unique identification of the session that has been created |
Call the API CallbackInputGet to retrieve the session id.
SessionAfterCreate is called immediately after the session has been created by the initial request. This is done before the site is loaded.
No direct effect - but the possibility to e.g. add roles to the session can result in significant effects on the site load.
If the initial request contains information that can be used to log a user in to the session, the user check and the update of the session can be done here. By updating the user and roles for the session (e.g. by calling the API SetUserAndUpdate) the site will be loaded as if the user had logged in using the "standard" login page.
| Field | Type | Condition | Description |
|---|---|---|---|
| UserID | Input | USERID | The unique identification of the user |
Call the API CallbackInputGet to retrieve the user id.
The function is called from the Insert event handler function on the Insert User page. It is called just after the call to the function creating the user if the creation has been successful.
None.
An example could be the case where the WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a new user is created in WebsydianExpress a corresponding user must be created in the other user tables.
The implemented callback function can read the information for the created user by calling the server API UserGet. It is then possible to call functions for creating users in the other tables.
| Field | Type | Condition | Description |
|---|---|---|---|
| User ID | Input | CB_USERID | The unique identification of the user. |
| Login Name | Input | CB_LOGIN | The login used by the deleted user. |
| UserSitekey | Input | CB_USERSITE | Identifies the site the user was assigned to. The combination of login name and site uniquely identifies the user. |
Call the API CallbackInputGet to retrieve the information.
The function is called from the Delete event handler function on the Confirm Delete User page. It is called just after the call to the function deleting the user if the deletion has been successful.
None.
The WebsydianExpress user table and other user tables used inside the company must be synchronized. Every time a user is deleted in WebsydianExpress the corresponding users must be deleted in the other user tables.
As the user at this point has been deleted more information cannot be found by calling API functions, but depending on how the user tables references each other either the user surrogate or the combination of login name and site key should be sufficient to identify the records in the other tables.
| Field | Type | Condition | Description |
|---|---|---|---|
| Session ID | Input | CB_SESSIONID | The unique identification of the session. |
Call the API CallbackInputGet to retrieve the information.
The function is called just after a user has logged into WebsydianExpress and the session has been updated with the user and user roles.
None.
This callback function can be used to add extra roles to the session after a user has logged in, based on some external information; e.g. an ERP system.
An example of an implemented callback function for the callback point session after create can be found below.
This implementation retrieves the session id, writes it to the message log, uses the session id to read all of the session data and writes the IP address to the message log.
H DFTACTGRP(*NO) ACTGRP(*CALLER) BNDDIR('QC2LE' : 'WIEXPRESS')
D/COPY *libl/QRPGLESRC,EXPRESS_H
**********************************************************************
* Test of callback function for session after create
*---------------------------------------------------------------------
* The function writes a message to the message log containing the
* callbackinput parameter specifying the session id
* After this, the retrieved value is used to read the session data
* and the IP address is written to the log.
**********************************************************************
D RC S 10I 0 inz(0)
D Value S like(ParmCallback.ParmValue)
D ReturnCode S 7A
D P DS likeds(ParmSess) inz(*likeds)
C *ENTRY PLIST
C parm ReturnCode
C eval ReturnCode = ''
* Retrieve the session id from memory - write it to the log
C eval RC = CallbackInputGet(CB_SESSIONID:
C Value)
C eval RC = Writelog(EC_INFORMATION:
C 'RPG ' +
C 'SessionAfterCreate. SessionID: ' +
C Value)
* Retrieve the session information and write the IP adress to the log
C eval P.SessionID = %dec(Value:15:0)
C eval RC = SessionGet(P.SessionID:
C P.SiteKey:
C P.FolderListID:
C P.UserID:
C P.Status:
C P.IPAddress:
C P.CreationDate:
C P.CreationTime:
C P.LastReqDate:
C P.LastReqTime:
C P.RequestCount)
C eval RC = WriteLog(EC_INFORMATION:
C 'IP: ' + P.IPAddress)
C RETURN