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 with 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 archive page.

This module is not available for iOS, tvOS or watchOS.

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. Furthermore 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 functions asynchronously perform the request given, outputting the fetched content into a range.

The low level API allows for streaming, setting request headers and cookies, and other advanced features.

Cheat Sheet
Function NameDescription
High level
downloaddownload("ftp.digitalmars.com/sieve.ds", "/tmp/downloaded-ftp-file") downloads file from URL to file system.
uploadupload("/tmp/downloaded-ftp-file", "ftp.digitalmars.com/sieve.ds"); uploads file from file system to URL.
getget("dlang.org") returns a char[] containing the dlang.org web page.
putput("dlang.org", "Hi") returns a char[] containing the dlang.org web page. after a HTTP PUT of "hi"
postpost("dlang.org", "Hi") returns a char[] containing the dlang.org web page. after a HTTP POST of "hi"
byLinebyLine("dlang.org") returns a range of char[] containing the dlang.org web page.
byChunkbyChunk("dlang.org", 10) returns a range of ubyte[10] containing the dlang.org web page.
byLineAsyncbyLineAsync("dlang.org") asynchronously returns a range of char[] containing the dlang.org web page.
byChunkAsyncbyChunkAsync("dlang.org", 10) asynchronously returns a range of ubyte[10] containing the dlang.org web page.
Low level
HTTPStruct for advanced HTTP usage
FTPStruct for advanced FTP usage
SMTPStruct for advanced SMTP usage

Members

Aliases

CurlCode
alias CurlCode = CURLcode

Equal to etc.c.curl.CURLcode

ThrowOnError
alias ThrowOnError = Flag!"throwOnError"

Flag to specify whether or not an exception is thrown on error.

Classes

CurlException
class CurlException

Exception thrown on errors in std.net.curl functions.

CurlTimeoutException
class CurlTimeoutException

Exception thrown on timeout errors in std.net.curl functions.

HTTPStatusException
class HTTPStatusException

Exception thrown on HTTP request failures, e.g. 404 Not Found.

Enums

CurlOption (from etc.c.curl)
enum CurlOption via public import etc.c.curl : CurlOption;

Functions

byChunk
auto byChunk(const(char)[] url, size_t chunkSize, Conn conn)

HTTP/FTP fetch content as a range of chunks.

byChunkAsync
auto byChunkAsync(const(char)[] url, const(PostUnit)[] postData, size_t chunkSize, size_t transmitBuffers, Conn conn)
auto byChunkAsync(const(char)[] url, size_t chunkSize, size_t transmitBuffers, Conn conn)

HTTP/FTP fetch content as a range of chunks asynchronously.

byLine
auto byLine(const(char)[] url, KeepTerminator keepTerminator, Terminator terminator, Conn conn)

HTTP/FTP fetch content as a range of lines.

byLineAsync
auto byLineAsync(const(char)[] url, const(PostUnit)[] postData, KeepTerminator keepTerminator, Terminator terminator, size_t transmitBuffers, Conn conn)
auto byLineAsync(const(char)[] url, KeepTerminator keepTerminator, Terminator terminator, size_t transmitBuffers, Conn conn)

HTTP/FTP fetch content as a range of lines asynchronously.

connect
T[] connect(const(char)[] url, HTTP conn)

HTTP connect request.

del
void del(const(char)[] url, Conn conn)

HTTP/FTP delete content.

download
void download(const(char)[] url, string saveToPath, Conn conn)

HTTP/FTP download to local file system.

get
T[] get(const(char)[] url, Conn conn)

HTTP/FTP get content.

options
T[] options(const(char)[] url, HTTP conn)

HTTP options request.

patch
T[] patch(const(char)[] url, const(PatchUnit)[] patchData, HTTP conn)

HTTP patch content.

post
T[] post(const(char)[] url, const(PostUnit)[] postData, HTTP conn)
T[] post(const(char)[] url, string[string] postDict, HTTP conn)

HTTP post content.

put
T[] put(const(char)[] url, const(PutUnit)[] putData, Conn conn)

HTTP/FTP put content.

trace
T[] trace(const(char)[] url, HTTP conn)

HTTP trace request.

upload
void upload(string loadFromPath, const(char)[] url, Conn conn)

Upload file from local files system using the HTTP or FTP protocol.

Static variables

server
TestServer server;

Test server

Structs

AutoProtocol
struct AutoProtocol

Connection type used when the URL should be used to auto detect the protocol.

Curl
struct 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
struct FTP

FTP client functionality.

HTTP
struct HTTP

Tracking progress:

SMTP
struct SMTP

Basic SMTP protocol support.

Variables

tlsInit
bool tlsInit;

Thread-local storage init

Examples

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:

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 is 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 performed by calling perform(), which is synchronous.

Meta

Credits

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

Authors

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