View source code
Display the source code in std/net/curl.d from which this page was generated on github.
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

Module std.net.curl

Networking client functionality as provided by libcurl. The libcurl library must be installed on the system in order to use this module.

Note

You may need to link to the curl library, e.g. by adding "libs": ["curl"] to your dub.json file if you are using DUB.

Windows x86 note: A DMD compatible libcurl static library can be downloaded from the dlang.org download page.

Compared to using libcurl directly this module allows simpler client code for common uses, requires no unsafe operations, and integrates better with the rest of the language. Futhermore it provides range access to protocols supported by libcurl both synchronously and asynchronously.

A high level and a low level API are available. The high level API is built entirely on top of the low level one.

The high level API is for commonly used functionality such as HTTP/FTP get. The byLineAsync and byChunkAsync provides asynchronous ranges that performs the request in another thread while handling a line/chunk in the current thread.

The low level API allows for streaming and other advanced features.

Cheat Sheet
Function Name Description
    High level
download download("ftp.digitalmars.com/sieve.ds", "/tmp/downloaded-ftp-file") downloads file from URL to file system.
upload upload("/tmp/downloaded-ftp-file", "ftp.digitalmars.com/sieve.ds"); uploads file from file system to URL.
get get("dlang.org") returns a char[] containing the dlang.org web page.
put put("dlang.org", "Hi") returns a char[] containing the dlang.org web page. after a HTTP PUT of "hi"
post post("dlang.org", "Hi") returns a char[] containing the dlang.org web page. after a HTTP POST of "hi"
byLine byLine("dlang.org") returns a range of char[] containing the dlang.org web page.
byChunk byChunk("dlang.org", 10) returns a range of ubyte[10] containing the dlang.org web page.
byLineAsync byLineAsync("dlang.org") returns a range of char[] containing the dlang.org web page asynchronously.
byChunkAsync byChunkAsync("dlang.org", 10) returns a range of ubyte[10] containing the dlang.org web page asynchronously.
    Low level
HTTP HTTP struct for advanced usage
FTP FTP struct for advanced usage
SMTP SMTP struct for advanced usage

Example

import std.net.curl, std.stdio;

// Return a char[] containing the content specified by a URL
auto content = get("dlang.org");

// Post data and return a char[] containing the content specified by a URL
auto content = post("mydomain.com/here.cgi", ["name1" : "value1", "name2" : "value2"]);

// Get content of file from ftp server
auto content = get("ftp.digitalmars.com/sieve.ds");

// Post and print out content line by line. The request is done in another thread.
foreach (line; byLineAsync("dlang.org", "Post data"))
    writeln(line);

// Get using a line range and proxy settings
auto client = HTTP();
client.proxy = "1.2.3.4";
foreach (line; byLine("dlang.org", client))
    writeln(line);

For more control than the high level functions provide, use the low level API:

Example

import std.net.curl, std.stdio;

// GET with custom data receivers
auto http = HTTP("dlang.org");
http.onReceiveHeader =
    (in char[] key, in char[] value) { writeln(key, ": ", value); };
http.onReceive = (ubyte[] data) { /+ drop +/ return data.length; };
http.perform();

First, an instance of the reference-counted HTTP struct is created. Then the custom delegates are set. These will be called whenever the HTTP instance receives a header and a data buffer, respectively. In this simple example, the headers are written to stdout and the data is ignored. If the request should be stopped before it has finished then return something less than data.length from the onReceive callback. See onReceiveHeader/onReceive for more information. Finally the HTTP request is effected by calling perform(), which is synchronous.

Credits

The functionally is based on libcurl. LibCurl is licensed under an MIT/X derivative license.

Functions

Name Description
byChunk HTTP/FTP fetch content as a range of chunks.
byChunkAsync HTTP/FTP fetch content as a range of chunks asynchronously.
byLine HTTP/FTP fetch content as a range of lines.
byLineAsync HTTP/FTP fetch content as a range of lines asynchronously.
connect HTTP connect request.
del HTTP/FTP delete content.
download HTTP/FTP download to local file system.
get HTTP/FTP get content.
options HTTP options request.
patch HTTP patch content.
post HTTP post content.
put HTTP/FTP put content.
trace HTTP trace request.
upload Upload file from local files system using the HTTP or FTP protocol.

Classes

Name Description
CurlException Exception thrown on errors in std.net.curl functions.
CurlTimeoutException Exception thrown on timeout errors in std.net.curl functions.
HTTPStatusException Exception thrown on HTTP request failures, e.g. 404 Not Found.

Structs

Name Description
AutoProtocol
Curl Wrapper to provide a better interface to libcurl than using the plain C API. It is recommended to use the HTTP/FTP etc. structs instead unless raw access to libcurl is needed.
FTP FTP client functionality.
HTTP HTTP client functionality.
SMTP Basic SMTP protocol support.

Aliases

Name Type Description
CurlCode int Equal to etc.c.curl.CURLcode
ThrowOnError Flag!("throwOnError") Flag to specify whether or not an exception is thrown on error.

Authors

Jonas Drewsen. Some of the SMTP code contributed by Jimmy Cao.

License

Boost License 1.0.

Comments