CodeSnip Old Code (SVN)

{
 * NsWebServices.UBase.pas
 *
 * Provides a base class for all objects that access web services.
 *
 * $Rev$
 * $Date$
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The Original Code is NsWebServices.UBase.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2010 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit NsWebServices.UBase;


interface


uses
  // Delphi
  SysUtils, Classes,
  // Indy
  IdHTTP, IdAntiFreeze, IdException,
  // Projects
  NsWebServices.UDownloadMonitor, UURIParams, UWebInfo;


type

  {
  TWebServiceProgressEvent:
    Type of event handler used to handle TBaseWebService.OnProgress events. Used
    to monitor download progress.
      @param Sender [in] Reference to TBaseWebService object triggering event.
      @param BytesToDate [in] Number of bytes downloaded.
      @param BytesExpected [in] Total number of bytes to be downloaded.
  }
  TWebServiceProgressEvent = procedure(Sender: TObject; const BytesToDate,
    BytesExpected: Integer) of object;

  TBaseWebService = class(TObject)
  private
    fHTTP: TIdHTTP;                         // Component used for HTTP requests
    fAntiFreeze: TIdAntiFreeze;             // Prevents HTTP requests blocking
    fScriptURI: string;                     // URI of web service
    fDownloadMonitor: TDownloadMonitor;     // Monitors download progress
    fOnProgress: TWebServiceProgressEvent;  // OnProgress event handler
    fWantProgress: Boolean;                 // Value of WantProgress property
  strict private
    procedure ValidateContent(const Content: TStream);
      {Validates content of stream by comparing MD5 checksum to MD5 received in
      HTTP header.
        @param Content [in] Data to be checked.
        @except EWebServiceFailure raised if Content is not valid.
      }
    function DoRequestAsText(const Requestor: TProc<TBytesStream>): string;
      {Gets text from web service using provided requestor. Text is decoded
      according to encoding specified in HTTP response header.
        @param Requestor [in] Anonymous method that makes request of web
          service.
        @return Response from web service as text.
        @except EWebServiceFailure raised if content type of response is not
          text.
      }
    function DoRequestRaw(const Requestor: TProc<TBytesStream>): TBytes;
      {Gets a raw byte stream from web service using provided requestor.
        @param Requestor [in] Anonymous method that makes request of web
          service.
        @return Reponse from web service as raw bytes.
      }
    procedure DoPostParams(const Params: TURIParams;
      const PostProc: TProc<TStream>);
      {Helper method that assists in performing POST requests that send encoded
      query strings. Converts query string to raw data, sets required content
      type then hands off actual POST request to a provided anonymous method.
        @param Params [in] Parameters to be POSTed.
        @param PostProc [in] Anonymous method that performs POST request and
          processes response.
      }
    function BuildURI(const Params: TURIParams = nil): string;
      {Builds a URI from web service name and any required parameters.
        @param Params [in] Parameters to append to URI as query string. May be
          empty or nil.
        @return Required URI.
      }
  strict protected
    procedure HandleException(const E: EIdException);
      {Handles likely exceptions generated by HTTP component and translates into
      own exception objects that are not detected as bugs and have more user
      friendly error messages.
        @param E [in] Exception to translate.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EWebConnectionError raised if EIdSocketError encoutered.
        @except Other EIdException exceptions or descendants are re-raised.
      }
    procedure DoProgress; virtual;
      {Triggers OnProgress event if assigned and WantProgress is True.
      }
    property WantProgress: Boolean read fWantProgress write fWantProgress;
      {Flag that indicates if progress reporting is required. When True the
      OnProgress event is triggered if assigned. The OnProgress event is not
      triggered if this property is False}
    function GetRaw(const Params: TURIParams = nil): TBytes;
      {Performs a GET request on web service with optional query string and
      returns response as raw data.
        @param Params [in] Optional parameters to include in query string.
        @return Response as raw byte array.
      }
    function GetText(const Params: TURIParams = nil): string;
      {Performs a GET request on web service with optional query string and
      returns response as text.
        @param Params [in] Optional parameters to include in query string.
        @return Response as text, decoded according to response header.
      }
    procedure GetStrings(const Params: TURIParams; const Strings: TStrings);
      overload;
      {Performs a GET request on web service with query string and stores
      response in string list.
        @param Params [in] Parameters to include in query string. May be empty
          or nil.
      }
    procedure GetStrings(const Strings: TStrings); overload;
      {Performs a GET request on web service and stores response in string list.
        @params Strings [in] String list that receives response.
      }
    function PostRaw(const Data: TStream): TBytes; overload;
      {Performs a POST request on web service sending data from a stream and
      returns response as raw data.
        @param Data [in] Data to be posted. Must not be nil.
        @return Response as raw byte array.
      }
    function PostText(const Data: TStream): string; overload;
      {Performs a POST request on web service sending data from a stream and
      returns response as text.
        @param Data [in] Data to be posted. Must not be nil.
        @return Response as text, decoded according to response header.
      }
    function PostRaw(const Params: TURIParams): TBytes; overload;
      {Performs a POST request on web service sending query strings and returns
      response as raw data.
        @param Params [in] Parameters to be posted. Must not be nil.
        @return Response as raw byte array.
      }
    function PostText(const Params: TURIParams): string; overload;
      {Performs a POST request on web service sending query strings and returns
      response as text.
        @param Params [in] Parameters to be posted. Must not be nil.
        @return Response as text, decoded according to response header.
      }
    procedure PostStrings(const Data: TStream; const Strings: TStrings);
      overload;
      {Performs a POST request on web service sending data from a stream and
      stores response in a string list.
        @param Data [in] Data to be posted. Must not be nil.
        @param Strings [in] String list that receives response.
      }
    procedure PostStrings(const Params: TURIParams; const Strings: TStrings);
      overload;
      {Performs a POST request on web service sending query strings and stores
      response in a string list.
        @param Params [in] Parameters to be posted. Must not be nil.
        @param Strings [in] String list that receives response.
      }
  public
    constructor Create(const WebInfo: TWebServiceInfo);
      {Constructor. Creates and initialises web service object.
        @param WebInfo [in] Information about the web service.
      }
    destructor Destroy; override;
      {Destructor. Tears down object.
      }
    property OnProgress: TWebServiceProgressEvent
      read fOnProgress write fOnProgress;
      {Event that can be triggered to monitor progress of downloads. Event is
      only triggered when WantProgress property is true}
  end;


implementation


uses
  // Indy
  IdCoderMIME, IdStack,
  // 3rd party
  PJMD5,
  // Project
  NsWebServices.UCharEncodings, NsWebServices.UExceptions, UConsts;


resourcestring
  // Error messages
  sWebConnectionError = 'There was a problem accessing the internet. Please '
    + 'check your web connection. '
    + 'If you are using a proxy server please check its configuration.'
    + EOL2
    + 'The error reported by Windows was: %0:s.';
  sWebValidationError = 'Validation error: checksum failed. This may have been '
    + 'a transmission error.';
  sWebBase64Error = 'Validation error: checksum not transmitted correctly.';
  sWebTextContentTypeError = 'Text content expected from web service.';


function Base64Decode(const EncodedText: string): TBytes;
  {Decodes Base64 encoded text into raw data.
    @param EncodedText [in] Base64 encoded text.
    @return Decoded data as byte array.
  }
var
  DecodedStm: TBytesStream; // stream that receives decoded data
  Decoder: TIdDecoderMIME;  // object used to perform decoding
begin
  Decoder := TIdDecoderMIME.Create(nil);
  try
    DecodedStm := TBytesStream.Create;
    try
      Decoder.DecodeBegin(DecodedStm);
      Decoder.Decode(EncodedText);
      Decoder.DecodeEnd;
      Result := DecodedStm.Bytes;
    finally
      DecodedStm.Free;
    end;
  finally
    Decoder.Free;
  end;
end;

{ TBaseWebService }

function TBaseWebService.BuildURI(const Params: TURIParams): string;
  {Builds a URI from web service name and any required parameters.
    @param Params [in] Parameters to append to URI as query string. May be
      empty or nil.
    @return Required URI.
  }
begin
  if not Assigned(Params) or Params.IsEmpty then
    Result := fScriptURI
  else
    Result := fScriptURI + '?' + Params.EncodedQueryString;
end;

constructor TBaseWebService.Create(const WebInfo: TWebServiceInfo);
  {Constructor. Creates and initialises web service object.
    @param WebInfo [in] Information about the web service.
  }
var
  ProxyInfo: TWebProxyInfo; // details of any proxy server
begin
  inherited Create;
  fAntiFreeze :=  TIdAntiFreeze.Create(nil);
  // Create and initialise HTTP request object
  fHTTP := TIdHTTP.Create(nil);
  fHTTP.HTTPOptions := fHTTP.HTTPOptions - [hoForceEncodeParams];
  fHTTP.Request.UserAgent := WebInfo.UserAgent;
  fHTTP.Request.Accept := WebInfo.MediaType + ', */*';
  fHTTP.Request.AcceptCharSet := TWSCharEncodings.AcceptCharSet;
  fHTTP.Request.AcceptLanguage := 'en-gb, en;q=0.8';
  // Get any proxy info and configure HTTP request object if necessary
  ProxyInfo := TWebInfo.WebProxyInfo;
  if ProxyInfo.UseProxy then
  begin
    fHTTP.ProxyParams.ProxyServer := ProxyInfo.IPAddress;
    fHTTP.ProxyParams.ProxyPort := ProxyInfo.Port;
    fHTTP.ProxyParams.ProxyUsername := ProxyInfo.UserName;
    fHTTP.ProxyParams.ProxyPassword := ProxyInfo.Password;
  end;
  // Record script URI for future use
  fScriptURI := WebInfo.ScriptURI;
  // Create object that monitors download progress
  fDownloadMonitor := TDownloadMonitor.Create(fHTTP, DoProgress);
end;

destructor TBaseWebService.Destroy;
  {Destructor. Tears down object.
  }
begin
  fDownloadMonitor.Free;
  fHTTP.Free;
  fAntiFreeze.Free;
  inherited;
end;

procedure TBaseWebService.DoPostParams(const Params: TURIParams;
  const PostProc: TProc<TStream>);
  {Helper method that assists in performing POST requests that send encoded
  query strings. Converts query string to raw data, sets required content type
  then hands off actual POST request to a provided anonymous method.
    @param Params [in] Parameters to be POSTed.
    @param PostProc [in] Anonymous method that performs POST request and
      processes response.
  }
var
  Data: TStream;  // contains data sent to web service as part of POST request
begin
  // Create URI encoded parameters and store in stream. Encoded parameters are
  // in ASCII format
  Data := TBytesStream.Create(
    TEncoding.ASCII.GetBytes(Params.EncodedQueryString)
  );
  Data.Position := 0;
  try
    // Perform POST
    fHTTP.Request.ContentType := 'application/x-www-form-urlencoded';
    try
      PostProc(Data);
    finally
      fHTTP.Request.ContentType := '';
    end;
  finally
    Data.Free;
  end;
end;

procedure TBaseWebService.DoProgress;
  {Triggers OnProgress event if assigned and WantProgress is True.
  }
begin
  if fWantProgress and Assigned(fOnProgress) then
    fOnProgress(
      Self, fDownloadMonitor.BytesReceived, fDownloadMonitor.BytesExpected
    );
end;

function TBaseWebService.DoRequestAsText(const Requestor: TProc<TBytesStream>):
  string;
  {Gets text from web service using provided requestor. Text is decoded
  according to encoding specified in HTTP response header.
    @param Requestor [in] Anonymous method that makes request of web service.
    @return Response from web service as text.
    @except EWebServiceFailure raised if content type of response is not text.
  }
var
  Content: TBytes;      // raw data received from web service
  Encoding: TEncoding;  // encoding specified as part of HTTP response
begin
  // Perform request, getting raw content
  Content := DoRequestRaw(Requestor);
  // Check for correct content type
  if AnsiPos('text/', fHTTP.Response.ContentType) = 0 then
    raise EWebServiceFailure.Create(sWebTextContentTypeError);
  // Get text from raw data, decoded according to HTTP response header
  Encoding := TWSCharEncodings.GetEncoding(fHTTP.Response.CharSet);
  try
    Result := Encoding.GetString(Content);
  finally
    if not TEncoding.IsStandardEncoding(Encoding) then
      Encoding.Free;
  end;
end;

function TBaseWebService.DoRequestRaw(const Requestor: TProc<TBytesStream>):
  TBytes;
  {Gets a raw byte stream from web service using provided requestor.
    @param Requestor [in] Anonymous method that makes request of web service.
    @return Reponse from web service as raw bytes.
  }
var
  Response: TBytesStream; // receives response from web service as raw bytes
begin
  // Set up request
  Response := TBytesStream.Create;
  try
    // Do request, recording response in byte stream
    try
      Requestor(Response);
    except
      on E: EIdException do
        HandleException(E);
    end;
    Response.Position := 0;
    // Process reponse
    if fHTTP.Response.HasContentLength then
      Response.SetSize(fHTTP.Response.ContentLength);
    if fHTTP.Response.RawHeaders.IndexOfName('Content-MD5') >= 0 then
      // Response has MD5 checksum: check content is OK
      ValidateContent(Response);
    Result := Response.Bytes;
  finally
    Response.Free;
  end;
end;

function TBaseWebService.GetRaw(const Params: TURIParams = nil): TBytes;
  {Performs a GET request on web service with optional query string and returns
  response as raw data.
    @param Params [in] Optional parameters to include in query string.
    @return Response as raw byte array.
  }
begin
  Result := DoRequestRaw(
    procedure(AResponse: TBytesStream)
    begin
      fHTTP.Get(BuildURI(Params), AResponse)
    end
  )
end;

procedure TBaseWebService.GetStrings(const Strings: TStrings);
  {Performs a GET request on web service and stores response in string list.
    @params Strings [in] String list that receives response.
  }
begin
  GetStrings(nil, Strings);
end;

procedure TBaseWebService.GetStrings(const Params: TURIParams;
  const Strings: TStrings);
  {Performs a GET request on web service with query string and stores response
  in string list.
    @param Params [in] Parameters to include in query string. May be empty or
      nil.
  }
begin
  Strings.Text := Trim(GetText(Params));
end;

function TBaseWebService.GetText(const Params: TURIParams = nil): string;
  {Performs a GET request on web service with optional query string and returns
  response as text.
    @param Params [in] Optional parameters to include in query string.
    @return Response as text, decoded according to response header.
  }
begin
  Result := DoRequestAsText(
    procedure(AResponse: TBytesStream)
    begin
      fHTTP.Get(BuildURI(Params), AResponse)
    end
  )
end;

procedure TBaseWebService.HandleException(const E: EIdException);
  {Handles likely exceptions generated by HTTP component and translates into own
  exception objects that are not detected as bugs and have more user friendly
  error messages.
    @param E [in] Exception to translate.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EWebConnectionError raised if EIdSocketError encoutered.
    @except Other EIdException exceptions or descendants are re-raised.
  }
begin
  if E is EIdHTTPProtocolException then
    raise EHTTPError.Create(E as EIdHTTPProtocolException)
  else if E is EIdSocketError then
    raise EWebConnectionError.CreateFmt(sWebConnectionError, [Trim(E.Message)])
  else
    raise E;
end;

function TBaseWebService.PostRaw(const Params: TURIParams): TBytes;
  {Performs a POST request on web service sending query strings and returns
  response as raw data.
    @param Params [in] Parameters to be posted. Must not be nil.
    @return Response as raw byte array.
  }
var
  RetVal: TBytes;
begin
  DoPostParams(
    Params,
    procedure(Data: TStream)
    begin
      RetVal := PostRaw(Data);
    end
  );
  Result := RetVal;
end;

function TBaseWebService.PostRaw(const Data: TStream): TBytes;
  {Performs a POST request on web service sending data from a stream and returns
  response as raw data.
    @param Data [in] Data to be posted. Must not be nil.
    @return Response as raw byte array.
  }
begin
  Result := DoRequestRaw(
    procedure(AResponse: TBytesStream)
    begin
      fHTTP.Post(fScriptURI, Data, AResponse)
    end
  );
end;

procedure TBaseWebService.PostStrings(const Params: TURIParams;
  const Strings: TStrings);
  {Performs a POST request on web service sending query strings and stores
  response in a string list.
    @param Params [in] Parameters to be posted. Must not be nil.
    @param Strings [in] String list that receives response.
  }
begin
  Strings.Text := Trim(PostText(Params));
end;

procedure TBaseWebService.PostStrings(const Data: TStream;
  const Strings: TStrings);
  {Performs a POST request on web service sending data from a stream and stores
  response in a string list.
    @param Data [in] Data to be posted. Must not be nil.
    @param Strings [in] String list that receives response.
  }
begin
  Strings.Text := Trim(PostText(Data));
end;

function TBaseWebService.PostText(const Params: TURIParams): string;
  {Performs a POST request on web service sending query strings and returns
  response as text.
    @param Params [in] Parameters to be posted. Must not be nil.
    @return Response as text, decoded according to response header.
  }
var
  RetVal: string;
begin
  DoPostParams(
    Params,
    procedure(Data: TStream)
    begin
      RetVal := PostText(Data);
    end
  );
  Result := RetVal;
end;

function TBaseWebService.PostText(const Data: TStream): string;
  {Performs a POST request on web service sending data from a stream and returns
  response as text.
    @param Data [in] Data to be posted. Must not be nil.
    @return Response as text, decoded according to response header.
  }
begin
  Result := DoRequestAsText(
    procedure(AResponse: TBytesStream)
    begin
      fHTTP.Post(fScriptURI, Data, AResponse)
    end
  );
end;

procedure TBaseWebService.ValidateContent(const Content: TStream);
  {Validates content of stream by comparing MD5 checksum to MD5 received in
  HTTP header.
    @param Content [in] Data to be checked.
    @except EWebServiceFailure raised if Content is not valid.
  }
var
  HeaderMD5Encoded: string;   // encoded md5 from Content-MD5 header
  HeaderMD5: TPJMD5Digest;    // decoded md5 from Content-MD5 header
  ContentMD5: TPJMD5Digest;   // md5 of Content stream
begin
  // get MD5 from header
  HeaderMD5Encoded := fHTTP.Response.RawHeaders.Values['Content-MD5'];
  try
    HeaderMD5 := Base64Decode(HeaderMD5Encoded);
  except
    raise EWebServiceFailure.Create(sWebBase64Error);
  end;
  // calculate MD5 of received content
  ContentMD5 := TPJMD5.Calculate(Content);
  // check that both MD5s are same and raise exception if not
  if HeaderMD5 <> ContentMD5 then
    raise EWebServiceFailure.Create(sWebValidationError);
end;

end.