Übergeben Sie eine Zeichenkette mit der URL
, mit der gearbeitet werden soll.
Der Parameter sollte eine Zeichenkette sein, die im folgenden Format
URL-codiert sein muss:
Eine ausführlichere Erläuterung des Formats finden Sie in RFC3986.
libcurl überprüft die Syntax nicht und verwendet diese Variable erst, wenn
die Übertragung erfolgt ist. Auch wenn Sie hier einen verrückten Wert
festlegen, gibt easy:SetOpt() immer noch #CURLE_OK
zurück.
Wenn der angegebenen URL ein Schemaname fehlt (z.B. "http://" oder "ftp://"
usw.), wird libcurl basierend auf dem Host eine Vermutung anstellen. Wenn der
äußerste Subdomänenname mit DICT, FTP, IMAP, LDAP, POP3 oder SMTP
übereinstimmt, wird dieses Protokoll verwendet, andernfalls wird HTTP
benutzt. Seit 7.45.0 kann das Raten durch Setzen eines Standardprotokolls
deaktiviert werden. Siehe #CURLOPT_DEFAULT_PROTOCOL
für Einzelheiten.
Sollte das vom Schema angegebene oder von libcurl aus dem Hostnamen
abgeleitete Protokoll von libcurl nicht unterstützt werden, wird
#CURLE_UNSUPPORTED_PROTOCOL
entweder vom Befehl easy:Perform()
oder multi:Perform( ) aufgerufen. Verwenden Sie curl_version_info
,
um detaillierte Informationen darüber zu erhalten, welche Protokolle von
der von Ihnen verwendeten libcurl-Version unterstützt werden.
#CURLOPT_PROTOCOLS
kann verwendet werden, um zu begrenzen, welche
Protokolle libcurl für diese Übertragung verwendet, unabhängig davon, für
welche Unterstützung libcurl kompiliert wurde. Dies kann hilfreich sein, wenn
Sie die URL von einer externen Quelle akzeptieren und die Zugänglichkeit
einschränken möchten.
Die Zeichenkette #CURLOPT_URL
wird ignoriert, wenn #CURLOPT_CURLU
festgelegt ist.
#CURLOPT_URL
oder #CURLOPT_CURLU
müssen gesetzt sein, bevor eine
Übertragung gestartet wird.
Der Host-Teil der URL enthält die Adresse des Servers, zu dem Sie eine
Verbindung herstellen möchten. Dies kann der vollständig qualifizierte
Domänenname des Servers, der lokale Netzwerkname des Computers
in Ihrem Netzwerk oder die IP-Adresse des Servers oder Computers sein,
die entweder durch eine IPv4- oder eine IPv6-Adresse dargestellt wird.
Zum Beispiel:
| http://www.example.com/
http://hostname/
http://192.168.0.1/
http://[2001:1890:1112:1::20]/
|
Es ist auch möglich, den Benutzernamen, das Passwort und alle unterstützten
Anmeldeoptionen als Teil des Hosts für die folgenden Protokolle anzugeben,
wenn eine Verbindung zu Servern hergestellt wird, die eine Authentifizierung
erfordern:
| http://user:password@www.example.com
ftp://user:password@ftp.example.com
smb://domain%2fuser:password@server.example.com
imap://user:password;options@mail.example.com
pop3://user:password;options@mail.example.com
smtp://user:password;options@mail.example.com
|
Derzeit unterstützen nur IMAP, POP3 und SMTP Anmeldeoptionen als Teil des
Hosts. Weitere Informationen zu den Anmeldeoptionen in der URL-Syntax finden
Sie unter RFC2384, RFC5092 und IETF-Entwurf "draft-earhart-url-smtp-00.txt"
(Hinzugefügt in 7.31.0).
Der Port ist optional und wenn nicht angegeben, verwendet libcurl den
Standardport basierend auf dem festgelegten oder angegebenen Protokoll:
80 für HTTP, 21 für FTP und 25 für SMTP usw. Die folgenden Beispiele zeigen,
wie der Port angegeben wird:
http://www.example.com:8080/
-
Dadurch wird eine Verbindung zu einem Webserver über Port 8080
anstelle von 80 hergestellt.
smtp://mail.example.com:587/
-
Dadurch wird eine Verbindung zu einem SMTP-Server am alternativen
Mail-Port hergestellt.
Der Pfadteil der URL ist protokollspezifisch und obwohl einige Beispiele
unter dieser Liste aufgeführt sind, ist dies nicht schlüssig:
HTTP
-
Der Pfadteil einer HTTP-Anforderung gibt die abzurufende Datei an und aus
welchem Verzeichnis. Wenn das Verzeichnis nicht angegeben ist, wird das
Stammverzeichnis des Webservers verwendet. Wenn die Datei weggelassen
wird, wird das Standarddokument entweder für das angegebene Verzeichnis
oder das Stammverzeichnis abgerufen. Die genaue Ressource, die für jede
URL zurückgegeben wird, hängt vollständig von der Serverkonfiguration ab.
http://www.example.com
-
Dies ruft die Hauptseite vom Webserver ab.
http://www.example.com/index.html
-
Dies gibt die Hauptseite zurück, indem sie explizit angefordert wird.
http://www.example.com/contactus/
-
Dies gibt das Standarddokument aus dem Kontaktverzeichnis zurück.
FTP
-
Der Pfadteil einer FTP-Anfrage gibt die abzurufende Datei an und aus welchem
Verzeichnis. Wenn der Dateiteil weggelassen wird, lädt libcurl die
Verzeichnisliste für das angegebene Verzeichnis herunter. Wenn das
Verzeichnis weggelassen wird, wird die Verzeichnisliste für das
Stammverzeichnis / Basisverzeichnis zurückgegeben.
ftp://ftp.example.com
-
Dadurch wird die Verzeichnisliste für das Stammverzeichnis abgerufen.
ftp://ftp.example.com/readme.txt
-
Dadurch wird die Datei readme.txt aus dem Stammverzeichnis heruntergeladen.
ftp://ftp.example.com/libcurl/readme.txt
-
Dadurch wird readme.txt aus dem libcurl-Verzeichnis heruntergeladen.
ftp://user:password@ftp.example.com/readme.txt
-
Das ruft die readme.txt-Datei aus dem Basisverzeichnis des Benutzers
ab. Wenn ein Benutzername und ein Passwort angegeben werden,
bezieht sich alles, was im Pfad angegeben wird, auf das Basisverzeichnis
des Benutzers. Um Dateien aus dem Stammverzeichnis oder einem
Verzeichnis unterhalb des Stammverzeichnisses abzurufen, muss
der absolute Pfad angegeben werden, indem ein zusätzlicher Schrägstrich
an den Anfang des Pfads angehängt wird.
ftp://user:password@ftp.example.com//readme.txt
-
Dadurch wird die Datei readme.txt aus dem Stammverzeichnis abgerufen,
wenn Sie sich als angegebener Benutzer anmelden.
SMTP
-
Der Pfadteil einer SMTP-Anforderung gibt den Hostnamen an, der während der
Kommunikation mit dem Mailserver angezeigt werden soll. Wenn der Pfad
weggelassen wird, versucht libcurl, den Hostnamen des lokalen Computers
aufzulösen. Dies gibt jedoch möglicherweise nicht den vollständig
qualifizierten Domänennamen zurück, der von einigen Mailservern benötigt
wird. Wenn Sie diesen Pfad angeben, können Sie einen alternativen Namen
festlegen, z.B. den vollständig qualifizierten Domänennamen Ihres Computers,
den Sie möglicherweise von einer externen Funktion erhalten haben, wie
gethostname oder getaddrinfo.
smtp://mail.example.com
-
Dadurch wird eine Verbindung zum Mailserver unter example.com
hergestellt und der Hostname Ihres lokalen Computers im Befehl
HELO/EHLO gesendet.
smtp://mail.example.com/client.example.com
-
Dadurch wird client.example.com im HELO/EHLO-Befehl an den Mailserver
unter example.com gesendet.
POP3
-
Der Pfadteil einer POP3-Anforderung gibt die abzurufende Nachrichten-ID an.
Wenn die ID nicht angegeben ist, wird stattdessen eine Liste anstehender
Nachrichten zurückgegeben.
pop3://user:password@mail.example.com
-
Hier werden die verfügbaren Nachrichten für den Benutzer aufgelistet.
pop3://user:password@mail.example.com/1
-
Dadurch wird die erste Nachricht für den Benutzer abgerufen.
IMAP
-
Der Pfadteil einer IMAP-Anfrage gibt nicht nur die Mailbox an, die
aufgelistet (hinzugefügt in 7.30.0) oder ausgewählt werden soll, sondern
kann auch dazu verwendet werden, die UIDVALIDITY der Mailbox zu überprüfen,
die UID, SECTION (hinzugefügt in 7.30.0) und PARTIELLE Oktette (hinzugefügt
in 7.37.0) der zu holenden Nachricht anzugeben und zu spezifizieren, nach
welchen Nachrichten gesucht werden soll (hinzugefügt in 7.37.0).
imap://user:password@mail.example.com
-
Führt eine Ordnerliste der obersten Ebene aus.
imap://user:password@mail.example.com/INBOX
-
Führt eine Ordnerliste im Posteingang des Benutzers durch.
imap://user:password@mail.example.com/INBOX/;UID=1
-
Wählt den Posteingang des Benutzers aus und ruft die Nachricht
mit uid = 1 ab.
imap://user:password@mail.example.com/INBOX/;MAILINDEX=1
-
Wählt den Posteingang des Benutzers aus und ruft die erste Nachricht
in der Mailbox ab.
imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2
-
Wählt den Posteingang des Benutzers aus, überprüft, ob die UIDVALIDITY
der Mailbox 50 beträgt und ruft die Nachricht 2 ab, falls dies
der Fall ist.
imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT
-
Wählt den Posteingang des Benutzers aus und ruft den Textteil
von Nachricht 3 ab.
imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024
-
Wählt den Posteingang des Benutzers aus und ruft die ersten
1024 Oktette der Nachricht 4 ab.
imap://user:password@mail.example.com/INBOX?NEW
-
Wählt den Posteingang des Benutzers aus und sucht nach NEUE Nachrichten.
imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows
-
Wählt den Posteingang des Benutzers aus und sucht in der Betreffzeile
nach Nachrichten, die "shadows" enthalten.
Weitere Informationen zu den einzelnen Komponenten einer IMAP-URL finden Sie
in RFC5092.
SCP
-
Der Pfadteil einer SCP-Anforderung gibt die abzurufende Datei sowie aus
welchem Verzeichnis an. Der Dateiteil darf nicht weggelassen werden. Die Datei
wird als absoluter Pfad aus dem Stammverzeichnis auf dem Server übernommen.
Wenn Sie einen Pfad relativ zum Basisverzeichnis des Benutzers auf dem Server
angeben möchten, stellen Sie ~/ vor den Pfadabschnitt. Wenn der Benutzername
nicht in die URL eingebettet ist, kann er mit der Option
#CURLOPT_USERPWD
oder
#CURLOPT_USERNAME
festgelegt werden.
scp://user@example.com/etc/issue
-
Dies gibt die Datei /etc/issue an.
scp://example.com/~/my-file
-
Dies gibt die Datei my-file im Home-Verzeichnis des Benutzers
auf dem Server an.
SFTP
-
Der Pfadteil einer SFTP-Anforderung gibt die abzurufende Datei sowie aus
welchem Verzeichnis an. Wenn der Dateiteil weggelassen wird, lädt libcurl die
Verzeichnisliste für das angegebene Verzeichnis herunter. Wenn der Pfad mit
einem / endet, wird anstelle einer Datei eine Verzeichnisliste zurückgegeben.
Wenn der Pfad vollständig weggelassen wird, wird die Verzeichnisliste für das
Stammverzeichnis / Basisverzeichnis zurückgegeben. Wenn der Benutzername
nicht in die URL eingebettet ist, kann er mit der Option
#CURLOPT_USERPWD
oder #CURLOPT_USERNAME
festgelegt werden.
sftp://user:password@example.com/etc/issue
-
Dies gibt die Datei /etc/issue an.
sftp://user@example.com/~/my-file
-
Dies gibt die Datei my-file im Home-Verzeichnis des Benutzers an.
sftp://ssh.example.com/~/Documents/
-
Dadurch wird eine Verzeichnisliste des Verzeichniss "Dokuments"
im Ausgangsverzeichnis des Benutzers angefordert.
SMB
-
Der Pfadteil einer SMB-Anforderung gibt die abzurufende Datei an (und darf
nicht ausgelassen werden), aus welchem Share und Verzeichnis oder in welches
Share hochgeladen werden soll. Wenn der Benutzername
nicht in die URL eingebettet ist, kann er mit der Option
#CURLOPT_USERPWD
oder #CURLOPT_USERNAME
festgelegt werden. Wenn der Benutzername in die
URL eingebettet ist, muss er den Domänennamen enthalten und als solcher
muss der umgekehrte Schrägstrich als %2f URL codiert sein.
smb://server.example.com/files/issue
-
Dies gibt die Datei "issue" an, die sich im Stammverzeichnis
der Freigabe "files" befindet.
smb://server.example.com/files/ -T issue
-
Dies legt fest, dass die Datei "issue" in das Stammverzeichnis
der Freigabe "files" hochgeladen wird.
LDAP
-
Der Pfadteil einer LDAP-Anfrage kann verwendet werden, um Folgendes anzugeben:
Distinguished Name, Attributes, Scope, Filter and Extension für eine LDAP-Suche.
Jedes Feld ist durch ein Fragezeichen getrennt. Wenn dieses Feld nicht
erforderlich ist, muss eine leere Zeichenkette mit dem
Fragezeichen-Trennzeichen eingefügt werden.
ldap://ldap.example.com/o=My%20Organisation
-
Dadurch wird eine LDAP-Suche mit dem DN My Organisation durchgeführt.
ldap://ldap.example.com/o=My%20Organisation?postalAddress
-
Dadurch wird dieselbe Suche durchgeführt, es werden jedoch nur
postalAddress-Attribute zurückgegeben.
ldap://ldap.example.com/?rootDomainNamingContext
-
Dies gibt einen leeren DN an und fordert Informationen zum Attribut
rootDomainNamingContext für einen aktiven Directory-Server an.
Weitere Informationen zu den einzelnen Komponenten einer LDAP-URL finden
Sie in RFC4516.
RTMP
-
Es gibt keine offizielle URL-Angaben für RTMP, daher verwendet libcurl
die URL-Syntax, die von der zugrunde liegenden Bibliothek librtmp unterstützt
wird. Sie hat eine Syntax, in der eine herkömmliche URL verwendet wird,
gefolgt von einem Leerzeichen und einer Reihe von durch Leerzeichen getrennten
name=value-Paaren.
Während Leerzeichen normalerweise kein "legal"er Buchstabe ist, akzeptiert
libcurl sie. Wenn ein Benutzer ein '#' (Hash-Zeichen) übergeben möchte, wird
es als Fragment behandelt und von libcurl abgeschnitten, wenn es wörtlich
angegeben wird. Sie müssen es stattdessen mit einem Backslash und dem
ASCII-Wert in hexadezimaler Schreibweise "\23" angeben.