Page 414
text *url); Parameters Return Values WRB_ICXcreateRequest() returns a handle to the newly created request object. WRB_ICXcreateRequest() returns NULL on failure.
Beyond creating request objects, you might want to also issue requests. The process for issuing requests is as follows:
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge method. text*url is a pointer to the URL of the request.
WRB_ICXdestroyRequest()This method frees resources WRB allocated for a specified request. It's good programming practice to free resources allocated to objects no longer in use. Listing 17.6 shows you how to destroy the request object after you're done with it.
Listing 17.6 Destroying a Request Object with WRB_ICXdestroyRequest()
WAPIReturnCode WRB_ICXdestroyRequest(void *WRBCtx, dvoid * hRequest); Parameters Return Values WRB_ICXdestroyRequest() returns a value of type WAPIReturnCode.
After a request is satisfied, you must invoke WRB_ICXdestroyRequest(). As long as you don't use WRB_ICXmakeRequest() to issue a request, you can use WRB_ICXdestroyRequest() to cancel a request that was created by WRB_ICXcreateRequest().
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge method. dvoid * hRequest identifies the request to be destroyed. The method WRB_ICXcreateRequest() would return this handle.
WRB_ICXfetchMoreData()WRB_ICXfetchMoreData() retrieves the requested number of bytes when a previous call to WRB_ICXmakeRequest() returns WRB_MOREDATA. If this requested number is more than is available, this method returns the number of bytes available. Listing 17.7 shows this method in detail.
Page 415
Listing 17.7 Getting More Data with WRB_ICXfetchMoreData()
WRBAPIReturnCode WRB_ICXfetchMoreData(dvoid *WRBCtx, dvoid *hRequest, dvoid **response, ub4 *responseLength, ub4 chunkSize); Parameters Return Values WRB_ICXfetchMoreData() returns a value of type WAPIReturnCode.
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge method. dvoid * hRequest identifies the request to be destroyed.
dvoid **response is a pointer to the location to which the method is to store a pointer to the response data. ub4 * responseLength is a pointer to the location to which the function is to store the length (in bytes) of the response data. If ub4 chunkSize has a non-zero value, the size of the request response in bytes will be restricted to this value. In such situations, you'll need to invoke the WRB_ICXfetchMoreData() method repeatedly until you've received the entire response. If ub4 chunkSize is zero, no data is returned.
If a call to WRB_ICXmakeRequest() returns WRB_MOREDATA, you can invoke this method as many times as necessary to get chunkSize additional bytes of the request response. This would need to be done until all response data has been received.
WRB_ICXgetHeaderVal()Before using this method, you must invoke the WRB_ICXmakeRequest() method, which issues a request. WRB_ICXgetHeaderVal() uses the response to this request to return the value of a specified HTTP header (see Listing 17.8).
Listing 17.8 Getting the Value of a Specific Response Header with WRB_ICXgetHeaderVal()
text * WRB_ICXgetHeaderVal(void *WRBCtx, dvoid * hRequest, text *name); Parameters Return Values WRB_ICXgetHeaderVal() returns the value of the specified header. WRB_ICXgetHeaderVal() returns NULL on failure.
WRB_ICXgetHeaderVal() returns the pointer to the value of a specified HTTP header from the response to a request issued by WRB_ICXmakeRequest(). The pointer can be quite valuable for retrieving response data that response headers contain.
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine dispatched to your cartridge method. dvoid * hRequest identifies the request for which the WRB
Page 416
extracts header value from the response. text * name is a pointer to the name of the header that you want.
WRB_ICXgetInfo()This method returns a character string containing information about a specified request. You can specify the kind of information you want back. Listing 17.9 details this method.
Listing 17.9 Getting Information About a Request with WRB_ICXgetInfo()
text * WRB_ICXgetInfo(void *WRBCtx, dvoid * hRequest, WRBInfoType infoType); Parameters Return Values WRB_ICXgetInfo() returns a pointer to the requested information as a character string. WRB_ICXgetInfo() returns NULL on failure.
When an ICX request is complete, you invoke WRB_ICXgetInfo() to get information about the request. The event that triggers this completion state is the completion and return of WRB_ICXmakeRequest(). The usefulness here is that you get the realm name in cases when WRB reissues the request with the proper authentication information.
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge function. dvoid * hRequest identifies the request about which you want information. Together, infoType and WRBInfoType represent a code that identifies the type of information you want. The infoType parameter specifies the kind of information to be returned.
WRB_ICXgetInfo() accepts an argument of type WRBInfoType that specifies the kind of request information to return to the caller. Listing 17.10 shows the structure of this type.
Listing 17.10 The WRBInfoType Enumerated Type
typedef enum _WRBInfoType { STATUSCODE, HTTPVERSION, REASONPHRASE, REALM } WRBInfoType; WRBInfoType Values
STATUSCODE represents the HTTP response code. HTTPVERSION represents the version of the HTTP protocol used in the response. REASONPHRASE represents the reason text string that corresponds to the HTTP response code. REALM represents the name of the authentication realm specified in the response.
Page 417
WRB_ICXgetParsedHeader()Before using this method, you must invoke WRB_ICXmakeRequest(), which issues a request. WRB_ ICXgetParsedHeader() uses the response to this request to return the value of a specified header. Listing 17.11 shows this method.
Listing 17.11 Getting Response Headers with WRB_ICXgetParsedHeader()
WAPIReturnCode WRB_ICXgetParsedHeader(void *WRBCtx, dvoid * hRequest, WRBpBlock *hPblock); Parameters Return Values WRB_ICXgetParsedHeader() returns a value of type WAPIReturnCode.
This method returns in the location pointed to by hPblock a parameter block containing the header values of the response to an ICX request issued by WRB_ICXmakeRequest(). The usefulness here is that you can retrieve response data that the response headers contain.
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge function. dvoid * hRequest identifies the request. WRBpBlock * hPblock is a pointer to the location to which the function is to store the parameter block containing the parsed header data.
WRB_ICXmakeRequest()This method issues the specified request. Listing 17.12 shows this method.
Listing 17.12 Issuing a Request with WRB_ICXmakeRequest()
WAPIReturnCode WRB_ICXmakeRequest(void *WRBCtx, dvoid * hRequest, void **response, ub4 *responseLength, ub4 chunkSize, ub1 sendToBrowser); Return Values WRB_ICXmakeRequest() returns a value of type WAPIReturnCode.
After you call WRB_ICXcreateRequest() to create a request and other ICX API functions such as WRB_ICXsetHeader() and WRB_ICXsetContent() to prepare the request, you can call WRB_ICXmakeRequest() to issue the request.
*WRBCtx is a pointer to the opaque WRB context object that the WRB application engine passed to your cartridge function. dvoid * hRequest identifies the request to be issued.
void ** response is a pointer to the location in which the function is to store a pointer to the response data. ub4 * responseLength is a pointer to the location to which the function is to store the length in bytes of the response data.