module OpenURI::OpenRead

OpenURI::OpenRead#open bietet 'open' für URI::HTTP und URI::FTP.

OpenURI::OpenRead#open nimmt optional 3 Argumente entgegen wie

OpenURI::OpenRead#open([mode [, perm]] [, options]) [{|io| ... }]

OpenURI::OpenRead#open gibt ein IO-ähnliches Objekt zurück, wenn kein Block angegeben ist. Andernfalls übergibt es das IO-Objekt und gibt den Wert des Blocks zurück. Das IO-Objekt wird mit OpenURI::Meta erweitert.

mode und perm sind dieselben wie bei Kernel#open.

mode muss jedoch im Lesemodus sein, da OpenURI::OpenRead#open den Schreibmodus (noch) nicht unterstützt. perm wird ebenfalls ignoriert, da es nur für die Dateierstellung von Bedeutung ist.

options muss ein Hash sein.

Jede Option mit einem String-Schlüssel gibt ein zusätzliches Header-Feld für HTTP an. Das heißt, es wird für FTP ohne HTTP-Proxy ignoriert.

Der Hash kann weitere Optionen enthalten, wobei die Schlüssel Symbole sind

:proxy

Zusammenfassung

:proxy => "http://proxy.foo.com:8000/"
:proxy => URI.parse("http://proxy.foo.com:8000/")
:proxy => true
:proxy => false
:proxy => nil

Wenn die Option :proxy angegeben ist, sollte der Wert ein String, eine URI, ein Boolean oder nil sein.

Wenn ein String oder eine URI angegeben wird, wird sie als Proxy-URI behandelt.

Wenn true angegeben wird oder die Option selbst nicht spezifiziert ist, wird die Umgebungsvariable 'scheme_proxy' geprüft. 'scheme' wird durch 'http', 'https' oder 'ftp' ersetzt.

Wenn false oder nil angegeben wird, werden die Umgebungsvariablen ignoriert und die Verbindung wird direkt zu einem Server hergestellt.

:proxy_http_basic_authentication

Zusammenfassung

:proxy_http_basic_authentication =>
  ["http://proxy.foo.com:8000/", "proxy-user", "proxy-password"]
:proxy_http_basic_authentication =>
  [URI.parse("http://proxy.foo.com:8000/"),
   "proxy-user", "proxy-password"]

Wenn die Option :proxy angegeben ist, sollte der Wert ein Array mit 3 Elementen sein. Er sollte eine Proxy-URI, einen Proxy-Benutzernamen und ein Proxy-Passwort enthalten. Die Proxy-URI sollte ein String, eine URI oder nil sein. Der Proxy-Benutzername und das Passwort sollten ein String sein.

Wenn nil für die Proxy-URI angegeben wird, wird diese Option einfach ignoriert.

Wenn :proxy und :proxy_http_basic_authentication angegeben sind, wird ein ArgumentError ausgelöst.

:http_basic_authentication

Zusammenfassung

:http_basic_authentication=>[user, password]

Wenn :http_basic_authentication angegeben ist, sollte der Wert ein Array mit 2 Strings sein: Benutzername und Passwort. Es wird für die HTTP Basic-Authentifizierung gemäß RFC 2617 verwendet.

:content_length_proc

Zusammenfassung

:content_length_proc => lambda {|content_length| ... }

Wenn die Option :content_length_proc angegeben ist, wird die Prozedur des Optionswerts aufgerufen, bevor die eigentliche Übertragung beginnt. Sie nimmt ein Argument entgegen, das die erwartete Inhaltslänge in Bytes ist.

Wenn zwei oder mehr Übertragungen aufgrund von HTTP-Umleitungen durchgeführt werden, wird die Prozedur nur einmal für die letzte Übertragung aufgerufen.

Wenn die erwartete Inhaltslänge unbekannt ist, wird die Prozedur mit nil aufgerufen. Dies geschieht, wenn die HTTP-Antwort keinen Content-Length-Header hat.

:progress_proc

Zusammenfassung

:progress_proc => lambda {|size| ...}

Wenn die Option :progress_proc angegeben ist, wird der Proc jedes Mal mit einem Argument aufgerufen, wenn 'open' ein Inhaltsfragment aus dem Netzwerk abruft. Das Argument size ist die akkumulierte übertragene Größe in Bytes.

Wenn zwei oder mehr Übertragungen durch HTTP-Umleitung erfolgen, wird der Proc nur einmal für die letzte Übertragung aufgerufen.

:progress_proc und :content_length_proc sind für Fortschrittsbalken gedacht. Zum Beispiel kann dies mit Ruby/ProgressBar wie folgt implementiert werden.

pbar = nil
open("http://...",
  :content_length_proc => lambda {|t|
    if t && 0 < t
      pbar = ProgressBar.new("...", t)
      pbar.file_transfer_mode
    end
  },
  :progress_proc => lambda {|s|
    pbar.set s if pbar
  }) {|f| ... }

:read_timeout

Zusammenfassung

:read_timeout=>nil     (no timeout)
:read_timeout=>10      (10 second)

Die Option :read_timeout gibt ein Timeout für das Lesen von HTTP-Verbindungen an.

:open_timeout

Zusammenfassung

:open_timeout=>nil     (no timeout)
:open_timeout=>10      (10 second)

Die Option :open_timeout gibt ein Timeout für das Öffnen von HTTP-Verbindungen an.

:ssl_ca_cert

Zusammenfassung

:ssl_ca_cert=>filename or an Array of filenames

:ssl_ca_cert wird verwendet, um ein CA-Zertifikat für SSL anzugeben. Wenn es angegeben ist, werden Standardzertifikate nicht verwendet.

:ssl_verify_mode

Zusammenfassung

:ssl_verify_mode=>mode

:ssl_verify_mode wird verwendet, um den Openssl-Verifizierungsmodus anzugeben.

:ssl_min_version

Zusammenfassung

:ssl_min_version=>:TLS1_2

Die Option :ssl_min_version gibt die minimal zulässige SSL/TLS-Protokollversion an. Siehe auch OpenSSL::SSL::SSLContext#min_version=.

:ssl_max_version

Zusammenfassung

:ssl_max_version=>:TLS1_2

Die Option :ssl_max_version gibt die maximal zulässige SSL/TLS-Protokollversion an. Siehe auch OpenSSL::SSL::SSLContext#max_version=.

:ftp_active_mode

Zusammenfassung

:ftp_active_mode=>bool

:ftp_active_mode => true wird verwendet, um den FTP-Active-Modus zu aktivieren. Ruby 1.9 verwendet standardmäßig den passiven Modus. Beachten Sie, dass der aktive Modus in Ruby 1.8 oder früher der Standard ist.

:redirect

Zusammenfassung

:redirect=>bool

:redirect ist standardmäßig true. :redirect => false wird verwendet, um alle HTTP-Umleitungen zu deaktivieren.

Die Ausnahme OpenURI::HTTPRedirect wird bei einer Umleitung ausgelöst. Die Verwendung von true bedeutet auch, dass Umleitungen zwischen HTTP und FTP zulässig sind.

:max_redirects

Zusammenfassung

:max_redirects=>int

Anzahl der erlaubten HTTP-Umleitungen, bevor ein OpenURI::TooManyRedirects ausgelöst wird. Der Standardwert ist 64.

:request_specific_fields

Zusammenfassung

:request_specific_fields => {}
:request_specific_fields => lambda {|url| ...}

Die Option :request_specific_fields ermöglicht die Angabe benutzerdefinierter Header-Felder, die mit der HTTP-Anfrage gesendet werden. Sie kann als Hash oder als Proc übergeben werden, der bei jeder Anfrage ausgewertet wird und einen Hash von Header-Feldern zurückgibt.

Wenn ein Hash bereitgestellt wird, gibt er die Header nur für die anfängliche Anfrage an und diese Header werden bei Umleitungen nicht gesendet.

Wenn ein Proc bereitgestellt wird, wird er für jede Anfrage, einschließlich Umleitungen, ausgeführt und ermöglicht die dynamische Anpassung von Headern basierend auf der Anfrage-URL. Es ist wichtig, dass der Proc einen Hash zurückgibt. Und dieser Hash gibt die mit der Anfrage zu sendenden Header an.

Beispiel mit Hash

URI.open("http://...",
         request_specific_fields: {"Authorization" => "token dummy"}) {|f| ... }

Beispiel mit Proc

URI.open("http://...",
         request_specific_fields: lambda { |uri|
           if uri.host == "example.com"
             {"Authorization" => "token dummy"}
           else
             {}
           end
         }) {|f| ... }

OpenURI::OpenRead#read([ options ]) liest den von self referenzierten Inhalt und gibt den Inhalt als String zurück. Der String wird mit OpenURI::Meta erweitert. Das Argument options ist dasselbe wie bei OpenURI::OpenRead#open.