The TServerRequest component is used to send/receive content to/from the web server. For client applications running in a web browser, any content sent using a server request must be textual and is normally sent to the web server as UTF-8-encoded text. For server applications, any content sent using a server request can be textual or binary, but textual data is also automatically encoded as UTF-8-encoded text. Both client applications and server applications can receive both textual and binary data, but client applications must deal with the received content as text and only server applications allow you to use streams to deal with binary data received in a response to a server request.

Use the following steps to execute a server request using a TServerRequest component:

• Make sure that the TServerRequest Method property is set to the desired value. The default value is rmGet.



• Assign the proper URL to the TServerRequest URL property.
  
  
   For client applications running in a web browser, if the origin (protocol, host, and port) specified in the URL is different than the origin for the application, then you will need to set the TServerRequest CrossOriginCredentials property to true in order to have any HTTP cookies and/or authentication headers sent to the web server that is servicing the HTTP requests for the URL.



• Assign any URL parameters to the TServerRequest Params property. The Params property is a TStringList object instance with an equals (=) name/value separator. Each parameter should be specified in the name=value format as a separate string in the list.
  
  
   URL parameters are automatically appended directly to the URL by the TServerRequest component when the Execute method is called, so do not add them directly to the URL property. You can use the CompleteURL property to retrieve the full URL that will be sent to the destination web server when the server request is executed.



• Assign any custom request headers to the TServerRequest Headers property. The Headers property is a TStringList object instance with a colon (:) name/value separator. Each header should be specified in the following format as a separate string in the list:
  
  

  Name: Value



• Create and assign an event handler to the TServerRequest OnComplete event. This will ensure that you can determine when the request is complete.



• Call the TServerRequest Execute method to initiate the web server request.
  
  
   Remember that the Execute method is asynchronous when used in client applications running in a web browser, and synchronous when used in server applications running in the web server.

TServerRequest Example

---

For example, suppose that you wanted to retrieve customer data from the web server in the following key-value format:

ID=100
Name=ACME Manufacturing, Inc.
Contact=Bob Smith
Address1=100 Main Street
Address2=
City=Bedford Falls
State=NY
ZipPostal=11178

To do so, you would use code like the following:

procedure TMyForm.MyFormCreate(Sender: TObject);
begin
   MyRequest:=TServerRequest.Create(nil);
end;

procedure TMyForm.MyFormDestroy(Sender: TObject);
begin
   MyRequest.Free;
end;

procedure TMyForm.RequestComplete(Request: TServerRequest);
begin
   if (Request.StatusCode=HTTP_OK) then
      ShowMessage('The value of the customer ID is '+
                  Request.ResponseContent.Values['ID'])
   else
      raise Exception.Create('Response Error: '+Request.StatusText);
end;

procedure TMyForm.GetCustomerClick(Sender: TObject);
begin
   MyRequest.URL:='/customer';
   MyRequest.Params.Add('method=info');
   MyRequest.OnComplete:=RequestComplete;
   MyRequest.Execute;
end;

TServerRequestQueue Example

---

To use the TServerRequestQueue component instead of the TServerRequest component, you would use the following code:

procedure TMyForm.MyFormCreate(Sender: TObject);
begin
   MyRequestQueue:=TServerRequestQueue.Create(nil);
end;

procedure TMyForm.MyFormDestroy(Sender: TObject);
begin
   MyRequestQueue.Free;
end;

procedure TMyForm.RequestComplete(Request: TServerRequest);
begin
   if (Request.StatusCode=HTTP_OK) then
      ShowMessage('The value of the customer ID is '+
                  Request.ResponseContent.Values['ID'])
   else
      raise Exception.Create('Response Error: '+Request.StatusText);
end;

procedure TMyForm.GetCustomerClick(Sender: TObject);
var
   TempRequest: TServerRequest;
begin
   TempRequest:=MyRequestQueue.GetNewRequest;
   TempRequest.URL:='/customer';
   TempRequest.Params.Add('method=info');
   TempRequest.OnComplete:=RequestComplete;
   MyRequestQueue.AddRequest(TempRequest);
end;

Cancelling a Server Request

---

Sometimes it is necessary to cancel a pending server request, and this can be done by calling TServerRequest Cancel method. If you're using a TServerRequestQueue component, then you can call the CancelRequest or CancelAllRequests methods to cancel one or more queued requests.

HTTP Response Status Codes

---

There are defined constants that represent the common HTTP response status codes in the WebHTTP unit:

   HTTP_NONE = 0;

   HTTP_CONTINUE= 100;

   HTTP_OK = 200;
   HTTP_CREATED = 201;

   HTTP_MOVED_PERMANENTLY = 301;
   HTTP_FOUND = 302;
   HTTP_SEE_OTHER = 303;
   HTTP_NOT_MODIFIED = 304;
   HTTP_MOVED_TEMPORARILY = 307;

   HTTP_BAD_REQUEST = 400;
   HTTP_FORBIDDEN = 403;
   HTTP_NOT_FOUND = 404;
   HTTP_METHOD_NOT_ALLOWED = 405;
   HTTP_NO_LENGTH = 411;
   HTTP_PAYLOAD_TOO_LARGE = 413;
   HTTP_HEADERS_TOO_LARGE = 431;

   HTTP_INTERNAL_ERROR = 500;
   HTTP_NOT_IMPLEMENTED = 501;
   HTTP_SERVICE_UNAVAILABLE = 503;
   HTTP_VERSION_NOT_SUPPORTED = 505;