httpsend.pas - fixed documentation

git-svn-id: https://svn.code.sf.net/p/synalist/code/trunk@156 7c85be65-684b-0410-a082-b2ed4fbef004

httpsend.pas

@@ -117,52 +117,53 @@ type
     constructor Create;
     destructor Destroy; override;
 
-    {:Reset headers and document and Mimetype.}
+    {:Reset headers, document and Mimetype.}
     procedure Clear;
 
     {:Decode ResultCode and ResultString from Value.}
     procedure DecodeStatus(const Value: string);
 
-    {:Connects to host define in URL and access to resource defined in URL by
+    {:Connects to host defined in URL and accesses resource defined in URL by
-     method. If Document is not empty, send it to server as part of HTTP request.
+     method. If Document is not empty, send it to the server as part of the HTTP
-     Server response is in Document and headers. Connection may be authorised
+     request. Server response is in Document and headers. Connection may be
-     by username and password in URL. If you define proxy properties, connection
+     authorised by username and password in URL. If you define proxy properties,
-     is made by this proxy. If all OK, result is @true, else result is @false.
+     connection is made by this proxy.
+     If all OK, result is @true, else result is @false.
 
-     If you use in URL 'https:' instead only 'http:', then your request is made
+     If you use 'https:' instead of 'http:' in the URL, your request is made
-     by SSL/TLS connection (if you not specify port, then port 443 is used
+     by SSL/TLS connection (if you do not specify port, then port 443 is used
-     instead standard port 80). If you use SSL/TLS request and you have defined
+     instead of standard port 80). If you use SSL/TLS request and you have
-     HTTP proxy, then HTTP-tunnel mode is automaticly used .}
+     defined HTTP proxy, then HTTP-tunnel mode is automatically used .}
     function HTTPMethod(const Method, URL: string): Boolean;
 
-    {:You can call this method from OnStatus event for break current data
+    {:You can call this method from OnStatus event to break current data
      transfer. (or from another thread.)}
     procedure Abort;
   published
     {:Before HTTP operation you may define any non-standard headers for HTTP
-     request, except of: 'Expect: 100-continue', 'Content-Length', 'Content-Type',
+     request, except: 'Expect: 100-continue', 'Content-Length', 'Content-Type',
      'Connection', 'Authorization', 'Proxy-Authorization' and 'Host' headers.
-     After HTTP operation contains full headers of returned document.}
+     After HTTP operation, it contains full headers of the returned document.}
     property Headers: TStringList read FHeaders;
 
-    {:This is stringlist with name-value stringlist pairs. Each this pair is one
+    {:Stringlist with name-value stringlist pairs. Each pair is one cookie.
-     cookie. After HTTP request is returned cookies parsed to this stringlist.
+     After the HTTP request is returned, cookies are parsed to this stringlist.
-     You can leave this cookies untouched for next HTTP request. You can also
+     You can leave these cookies untouched for next HTTP requests. You can also
      save this stringlist for later use.}
     property Cookies: TStringList read FCookies;
 
-    {:Stream with document to send (before request, or with document received
+    {:Stream with document to send (before request), or with document received
      from HTTP server (after request).}
     property Document: TMemoryStream read FDocument;
 
-    {:If you need download only part of requested document, here specify
+    {:If you need to download only part of a requested document, specify here
-     possition of subpart begin. If here 0, then is requested full document.}
+     the position of subpart begin. If 0, the full document is requested.}
     property RangeStart: integer read FRangeStart Write FRangeStart;
 
-    {:If you need download only part of requested document, here specify
+    {:If you need to download only part of a requested document, specify here
-     possition of subpart end. If here 0, then is requested document from
+     the position of subpart end. If 0, the document from rangeStart to end of
-     rangeStart to end of document. (for broken download restoration,
+     document is requested.
-     for example.)}
+     (Useful for resuming broken downloads, for example.)}
     property RangeEnd: integer read FRangeEnd Write FRangeEnd;
 
     {:Mime type of sending data. Default is: 'text/html'.}
@@ -178,8 +179,8 @@ type
     {:Define timeout for keepalives in seconds!}
     property KeepAliveTimeout: integer read FKeepAliveTimeout Write FKeepAliveTimeout;
 
-    {:if @true, then server is requested for 100status capability when uploading
+    {:if @true, then the server is requested for 100status capability when
-     data. Default is @false (off).}
+     uploading data. Default is @false (off).}
     property Status100: Boolean read FStatus100 Write FStatus100;
 
     {:Address of proxy server (IP address or domain name) where you want to
@@ -189,50 +190,49 @@ type
     {:Port number for proxy connection. Default value is 8080.}
     property ProxyPort: string read FProxyPort Write FProxyPort;
 
-    {:Username for connect to proxy server where you want to connect in
+    {:Username for connection to proxy server used in HTTPMethod method.}
-     HTTPMethod method.}
     property ProxyUser: string read FProxyUser Write FProxyUser;
 
-    {:Password for connect to proxy server where you want to connect in
+    {:Password for connection to proxy server used in HTTPMethod method.}
-     HTTPMethod method.}
     property ProxyPass: string read FProxyPass Write FProxyPass;
 
-    {:Here you can specify custom User-Agent indentification. By default is
+    {:Here you can specify custom User-Agent identification.
-     used: 'Mozilla/4.0 (compatible; Synapse)'}
+     Default: 'Mozilla/4.0 (compatible; Synapse)'}
     property UserAgent: string read FUserAgent Write FUserAgent;
 
-    {:After successful @link(HTTPMethod) method contains result code of
+    {:Operation result code after successful @link(HTTPMethod) method.}
-     operation.}
     property ResultCode: Integer read FResultCode;
 
-    {:After successful @link(HTTPMethod) method contains string after result code.}
+    {:Operation result string after successful @link(HTTPMethod) method.}
     property ResultString: string read FResultString;
 
-    {:if this value is not 0, then data download pending. In this case you have
+    {:if this value is not 0, then data download is pending. In this case you
-     here total sice of downloaded data. It is good for draw download
+     have here the total size of downloaded data. Useful for drawing download
      progressbar from OnStatus event.}
     property DownloadSize: integer read FDownloadSize;
 
-    {:if this value is not 0, then data upload pending. In this case you have
+    {:if this value is not 0, then data upload is pending. In this case you have
-     here total sice of uploaded data. It is good for draw upload progressbar
+     here the total size of uploaded data. Useful for drawing upload progressbar
      from OnStatus event.}
     property UploadSize: integer read FUploadSize;
-    {:Socket object used for TCP/IP operation. Good for seting OnStatus hook, etc.}
+
+    {:Socket object used for TCP/IP operation.
+     Good for setting OnStatus hook, etc.}
     property Sock: TTCPBlockSocket read FSock;
 
-    {:To have possibility to switch off port number in 'Host:' HTTP header, by
+    {:Allows to switch off port number in 'Host:' HTTP header. By default @TRUE.
-    default @TRUE. Some buggy servers not like port informations in this header.}
+     Some buggy servers do not like port informations in this header.}
     property AddPortNumberToHost: Boolean read FAddPortNumberToHost write FAddPortNumberToHost;
   end;
 
-{:A very usefull function, and example of use can be found in the THTTPSend
+{:A very useful function, and example of use can be found in the THTTPSend
  object. It implements the GET method of the HTTP protocol. This function sends
  the GET method for URL document to an HTTP server. Returned document is in the
  "Response" stringlist (without any headers). Returns boolean TRUE if all went
  well.}
 function HttpGetText(const URL: string; const Response: TStrings): Boolean;
 
-{:A very usefull function, and example of use can be found in the THTTPSend
+{:A very useful function, and example of use can be found in the THTTPSend
  object. It implements the GET method of the HTTP protocol. This function sends
  the GET method for URL document to an HTTP server. Returned document is in the
  "Response" stream. Returns boolean TRUE if all went well.}
@@ -241,7 +241,7 @@ function HttpGetBinary(const URL: string; const Response: TStream): Boolean;
 {:A very useful function, and example of use can be found in the THTTPSend
  object. It implements the POST method of the HTTP protocol. This function sends
  the SEND method for a URL document to an HTTP server. The document to be sent
- is located in "Data" stream. The returned document is in the "Data" stream.
+ is located in the "Data" stream. The returned document is in the "Data" stream.
  Returns boolean TRUE if all went well.}
 function HttpPostBinary(const URL: string; const Data: TStream): Boolean;
 
@@ -251,18 +251,19 @@ function HttpPostBinary(const URL: string; const Data: TStream): Boolean;
  an HTTP server. You must prepare the form data in the same manner as you would
  the URL data, and pass this prepared data to "URLdata". The following is
  a sample of how the data would appear: 'name=Lukas&field1=some%20data'.
- The information in the field must be encoded by EncodeURLElement function.
+ The information in the field must be encoded by the EncodeURLElement function.
  The returned document is in the "Data" stream. Returns boolean TRUE if all
  went well.}
 function HttpPostURL(const URL, URLData: string; const Data: TStream): Boolean;
 
 {:A very useful function, and example of use can be found in the THTTPSend
  object. It implements the POST method of the HTTP protocol. This function sends
- the POST method for a URL document to an HTTP server. This function simulate
+ the POST method for a URL document to an HTTP server. This function simulates
- posting of file by HTML form used method 'multipart/form-data'. Posting file
+ posting of file by HTML form using the 'multipart/form-data' method. The posted
- is in DATA stream. Its name is Filename string. Fieldname is for name of
+ file is in the DATA stream. Its name is Filename string. Fieldname is for the
- formular field with file. (simulate HTML INPUT FILE) The returned document is
+ name of the form field with the file. (simulates HTML INPUT FILE) The returned
- in the ResultData Stringlist. Returns boolean TRUE if all went well.}
+ document is in the ResultData Stringlist. Returns boolean TRUE if all
+ went well.}
 function HttpPostFile(const URL, FieldName, FileName: string;
   const Data: TStream; const ResultData: TStrings): Boolean;