{
* This Source Code Form is subject to the terms of the Mozilla Public License,
* v. 2.0. If a copy of the MPL was not distributed with this file, You can
* obtain one at http://mozilla.org/MPL/2.0/
*
* Copyright (C) 2005-2013, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Implements a class that provides basic interaction with DelphiDabbler
* standard web services via HTTP.
}
unit Web.UStdWebService;
interface
uses
// Delphi
SysUtils, Classes,
// Project
UURIParams, Web.UBaseWebService;
type
/// <summary>Base class for web services that interact with standard
/// DelphiDabbler web services.</summary>
/// <remarks>
/// <para>Standard web services always place a numeric status code in first
/// line of the response followed by any resulting data. The status code is
/// zero for normal responses and non-zero when an error response is
/// returned.</para>
/// <para>This class outputs data for normal responses and generates
/// EWebServiceError exceptions for error responses, using the response data
/// as the error message. Malformed responses generate EWebServiceFailure
/// exceptions.</para>
/// </remarks>
TStdWebService = class(TBaseWebService)
strict protected
/// <summary>Converts string S into a form that is suitable for sending to
/// the a web service.</summary>
class function SanitiseString(const S: string): string;
/// <summary>Analyses lines of text returned from web services and extracts
/// the data component of successful responses. Exceptions are raised for
/// error responses using the returned text as the exception message.
/// </summary>
/// <param name="Response">TStrings [in] When the method is called Response
/// must contain the lines of text received from the web service. After
/// processing the first line containing the status code is removed,
/// leaving only 0 or more lines of data.</param>
/// <exception>EWebServiceError raised on receipt of a valid error
/// response.</exception>
/// <exception>EWebServiceFailure raised if the format of the response is
/// invalid.</exception>
procedure ProcessResponse(const Response: TStrings);
/// <summary>Posts a command to the web service and returns the data
/// component of the response in a string list.</summary>
/// <param name="Cmd">string [in] Command to be executed.</param>
/// <param name="Params">TURIParams [in] Parameters associated with the
/// command.</param>
/// <param name="Response">TStrings [in] String list set to reponse from
/// web service, stripped of the status code, where each line of the
/// response is a line of the string list.</param>
/// <exception>EWebServiceError raised on receipt of a valid error
/// response.</exception>
/// <exception>EWebServiceFailure raised if the web service returns an
/// invalid response.</exception>
/// <exception>EWebConnectionError raised if an EIdSocketError is
/// encountered.</exception>
/// <exception>EWebTransmissionError raised if response data is garbled in
/// transmission.</exception>
/// <exception>EHTTPError raised if an EIdHTTPProtocolException exception
/// is encountered.</exception>
/// <exception>Trapped EIdException or descendant exceptions are re-raised.
/// </exception>
procedure PostCommand(const Cmd: string; const Params: TURIParams;
const Response: TStrings);
/// <summary>Posts a query string to the web service and returns the data
/// component of the response in a string list.</summary>
/// <param name="Params">TURIParams [in] Parameters for inclusion in query
/// string.</param>
/// <param name="Response">TStrings [in] String list set to reponse from
/// web service, stripped of the status code, where each line of the
/// response is a line of the string list.</param>
/// <exception>EWebServiceError raised on receipt of a valid error
/// response.</exception>
/// <exception>EWebServiceFailure raised if the web service returns an
/// invalid response.</exception>
/// <exception>EWebConnectionError raised if an EIdSocketError is
/// encountered.</exception>
/// <exception>EWebTransmissionError raised if response data is garbled in
/// transmission.</exception>
/// <exception>EHTTPError raised if an EIdHTTPProtocolException exception
/// is encountered.</exception>
/// <exception>Trapped EIdException or descendant exceptions are re-raised.
/// </exception>
procedure PostQuery(const Query: TURIParams; const Response: TStrings);
/// <summary>Posts raw data to the web service and returns the data
/// component of the response in a string list.</summary>
/// <param name="Data">TStream [in] Stream containing data to be posted.
/// </param>
/// <param name="Response">TStrings [in] String list set to reponse from
/// web service, stripped of the status code, where each line of the
/// response is a line of the string list.</param>
/// <exception>EWebServiceError raised on receipt of a valid error
/// response.</exception>
/// <exception>EWebServiceFailure raised if the web service returns an
/// invalid response.</exception>
/// <exception>EWebConnectionError raised if an EIdSocketError is
/// encountered.</exception>
/// <exception>EWebTransmissionError raised if response data is garbled in
/// transmission.</exception>
/// <exception>EHTTPError raised if an EIdHTTPProtocolException exception
/// is encountered.</exception>
/// <exception>Trapped EIdException or descendant exceptions are re-raised.
/// </exception>
procedure PostData(const Data: TStream; const Response: TStrings); overload;
/// <summary>Posts raw data to the web service and returns the data
/// component of the response in a string list.</summary>
/// <param name="Data">TBytes [in] Byte array containing data to be posted.
/// </param>
/// <param name="Response">TStrings [in] String list set to reponse from
/// web service, stripped of the status code, where each line of the
/// response is a line of the string list.</param>
/// <exception>EWebServiceError raised on receipt of a valid error
/// response.</exception>
/// <exception>EWebServiceFailure raised if the web service returns an
/// invalid response.</exception>
/// <exception>EWebConnectionError raised if an EIdSocketError is
/// encountered.</exception>
/// <exception>EWebTransmissionError raised if response data is garbled in
/// transmission.</exception>
/// <exception>EHTTPError raised if an EIdHTTPProtocolException exception
/// is encountered.</exception>
/// <exception>Trapped EIdException or descendant exceptions are re-raised.
/// </exception>
procedure PostData(const Data: TBytes; const Response: TStrings); overload;
end;
implementation
uses
// Project
UStrUtils, Web.UExceptions;
{ TStdWebService }
resourcestring
// Error messages
sEmptyResponse = 'Empty response received from web service';
sBadStatusCode = 'Web service returned response with bad status code';
sUnrecognizedError = 'Unrecognized error notified by web service';
procedure TStdWebService.PostCommand(const Cmd: string;
const Params: TURIParams; const Response: TStrings);
begin
Params.Add('cmd', Cmd);
PostQuery(Params, Response);
end;
procedure TStdWebService.PostData(const Data: TBytes; const Response: TStrings);
begin
PostStrings(Data, Response);
ProcessResponse(Response);
end;
procedure TStdWebService.PostData(const Data: TStream;
const Response: TStrings);
begin
PostStrings(Data, Response);
ProcessResponse(Response);
end;
procedure TStdWebService.PostQuery(const Query: TURIParams;
const Response: TStrings);
begin
PostStrings(Query, Response);
ProcessResponse(Response);
end;
procedure TStdWebService.ProcessResponse(const Response: TStrings);
var
StatusCode: Integer; // status code from response
begin
// All responses have content => empty reponse is error
if Response.Count = 0 then
raise EWebServiceFailure.Create(sEmptyResponse);
// All valid responses have status code as first line of response
if not TryStrToInt(Response[0], StatusCode) then
raise EWebServiceFailure.Create(sBadStatusCode);
// We have got status code: chop it off to leave data in Response
Response.Delete(0);
// Check status code in first line: 0 => OK, otherwise error
if StatusCode <> 0 then
begin
// Error response: raise web service error exception unless data doesn't
// contain expected error message when failure exception is raised
if StrTrim(Response.Text) = '' then
raise EWebServiceFailure.Create(sUnrecognizedError);
raise EWebServiceError.Create(StrTrim(Response.Text), StatusCode);
end
end;
class function TStdWebService.SanitiseString(const S: string): string;
const
IllegalChars = [#$00..#$1F, #$7F];
var
Idx: Integer;
begin
Result := S;
for Idx := 1 to Length(S) do
if CharInSet(Result[Idx], IllegalChars) then
Result[Idx] := ' ';
end;
end.
