Category | Functions |
---|---|
High level | download upload get post put del options trace connect byLine byChunk byLineAsync byChunkAsync |
Low level | HTTP FTP SMTP |
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 string containing the dlang.org web page. |
put | put("dlang.org", "Hi") returns a string containing the dlang.org web page. after a HTTP PUT of "hi" |
post | post("dlang.org", "Hi") returns a string containing the dlang.org web page. after a HTTP POST of "hi" |
byLine | byLine("dlang.org") returns a range of strings 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 strings 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 |
import std.net.curl, std.stdio; // Return a string containing the content specified by an URL string content = get("dlang.org"); // Post data and return a string containing the content specified by an URL string content = post("mydomain.com/here.cgi", "post data"); // Get content of file from ftp server string 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);
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();
Connection type used when the URL should be used to auto detect the protocol.
This struct is used as placeholder for the connection parameter when calling
the high level API and the connection type (HTTP/FTP) should be guessed by
inspecting the URL parameter.
The rules for guessing the protocol are:
1, if URL starts with ftp://, ftps:// or ftp. then FTP connection is assumed.
2, HTTP connection otherwise.
import std.net.curl; // Two requests below will do the same. string content; // Explicit connection provided content = get!HTTP("dlang.org"); // Guess connection type by looking at the URL content = get!AutoProtocol("ftp://foo.com/file"); // and since AutoProtocol is default this is the same as connect = get("ftp://foo.com/file"); // and will end up detecting FTP from the url and be the same as connect = get!FTP("ftp://foo.com/file");
HTTP/FTP download to local file system.
const(char)[] url | resource to download |
string saveToPath | path to store the downloaded content on local disk |
Conn conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will guess connection type and create a new instance for this call only. |
import std.net.curl; download("ftp.digitalmars.com/sieve.ds", "/tmp/downloaded-ftp-file"); download("d-lang.appspot.com/testUrl2", "/tmp/downloaded-http-file");
Upload file from local files system using the HTTP or FTP protocol.
string loadFromPath | path load data from local disk. |
const(char)[] url | resource to upload to |
Conn conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will guess connection type and create a new instance for this call only. |
import std.net.curl; upload("/tmp/downloaded-ftp-file", "ftp.digitalmars.com/sieve.ds"); upload("/tmp/downloaded-http-file", "d-lang.appspot.com/testUrl2");
HTTP/FTP get content.
const(char)[] url | resource to get |
Conn conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. |
import std.net.curl; string content = get("d-lang.appspot.com/testUrl2");
HTTP post content.
const(char)[] url | resource to post to |
const(PostUnit)[] postData | data to send as the body of the request. An array of an arbitrary type is accepted and will be cast to ubyte[] before sending it. |
HTTP conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. |
import std.net.curl; string content = post("d-lang.appspot.com/testUrl2", [1,2,3,4]);
HTTP/FTP put content.
const(char)[] url | resource to put |
const(PutUnit)[] putData | data to send as the body of the request. An array of an arbitrary type is accepted and will be cast to ubyte[] before sending it. |
Conn conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. |
import std.net.curl; string content = put("d-lang.appspot.com/testUrl2", "Putting this data");
HTTP/FTP delete content.
const(char)[] url | resource to delete |
Conn conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will guess connection type and create a new instance for this call only. |
import std.net.curl; del("d-lang.appspot.com/testUrl2");
HTTP options request.
const(char)[] url | resource make a option call to |
const(OptionsUnit)[] optionsData | options data to send as the body of the request. An array of an arbitrary type is accepted and will be cast to ubyte[] before sending it. |
HTTP conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. Currently the HTTP RFC does not specify any usage of the optionsData and for this reason the example below does not send optionsData to the server. |
import std.net.curl; auto http = HTTP(); options("d-lang.appspot.com/testUrl2", null, http); writeln("Allow set to " ~ http.responseHeaders["Allow"]);
HTTP trace request.
const(char)[] url | resource make a trace call to |
HTTP conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. |
import std.net.curl; trace("d-lang.appspot.com/testUrl1");
HTTP connect request.
const(char)[] url | resource make a connect to |
HTTP conn | connection to use e.g. FTP or HTTP. The default AutoProtocol will
guess connection type and create a new instance for this call only.
The template parameter T specifies the type to return. Possible values are char and ubyte to return char[] or ubyte[]. |
import std.net.curl; connect("d-lang.appspot.com/testUrl1");
struct ByLineBuffer(Char) { bool linePresent; bool EOF; Char[] buffer; ubyte[] decodeRemainder;
bool append(const(ubyte)[] data)
{
byLineBuffer ~= data;
}
@property bool linePresent()
{
return byLinePresent;
}
Char[] get()
{
if (!linePresent)
{
// Decode ubyte[] into Char[] until a Terminator is found.
// If not Terminator is found and EOF is false then raise an
// exception.
}
return byLineBuffer;
}
}
HTTP/FTP fetch content as a range of lines.
A range of lines is returned when the request is complete. If the method or
other request properties is to be customized then set the conn parameter
with a HTTP/FTP instance that has these properties set.
import std.net.curl, std.stdio; foreach (line; byLine("dlang.org")) writeln(line);
const(char)[] url | The url to receive content from |
KeepTerminator keepTerminator | KeepTerminator.yes signals that the line terminator should be returned as part of the lines in the range. |
Terminator terminator | The character that terminates a line |
Conn conn | The connection to use e.g. HTTP or FTP. |
HTTP/FTP fetch content as a range of chunks.
A range of chunks is returned when the request is complete. If the method or other request properties is to be customized then set the conn parameter with a HTTP/FTP instance that has these properties set.
import std.net.curl, std.stdio; foreach (chunk; byChunk("dlang.org", 100)) writeln(chunk); // chunk is ubyte[100]
const(char)[] url | The url to receive content from |
size_t chunkSize | The size of each chunk |
Conn conn | The connection to use e.g. HTTP or FTP. |
HTTP/FTP fetch content as a range of lines asynchronously.
A range of lines is returned immediately and the request that fetches the
lines is performed in another thread. If the method or other request
properties is to be customized then set the conn parameter with a
HTTP/FTP instance that has these properties set.
If postData is non-null the method will be set to post for HTTP
requests.
The background thread will buffer up to transmitBuffers number of lines
before it stops receiving data from network. When the main thread reads the
lines from the range it frees up buffers and allows for the background thread
to receive more data from the network.
If no data is available and the main thread accesses the range it will block
until data becomes available. An exception to this is the wait(Duration) method on
the AsyncLineInputRange
. This method will wait at maximum for the
specified duration and return true if data is available.
import std.net.curl, std.stdio; // Get some pages in the background auto range1 = byLineAsync("www.google.com"); auto range2 = byLineAsync("www.wikipedia.org"); foreach (line; byLineAsync("dlang.org")) writeln(line); // Lines already fetched in the background and ready foreach (line; range1) writeln(line); foreach (line; range2) writeln(line);
import std.net.curl, std.stdio; // Get a line in a background thread and wait in // main thread for 2 seconds for it to arrive. auto range3 = byLineAsync("dlang.com"); if (range.wait(dur!"seconds"(2))) writeln(range.front); else writeln("No line received after 2 seconds!");
const(char)[] url | The url to receive content from |
const(PostUnit)[] postData | Data to HTTP Post |
KeepTerminator keepTerminator | KeepTerminator.yes signals that the line terminator should be returned as part of the lines in the range. |
Terminator terminator | The character that terminates a line |
size_t transmitBuffers | The number of lines buffered asynchronously |
Conn conn | The connection to use e.g. HTTP or FTP. |
HTTP/FTP fetch content as a range of chunks asynchronously.
A range of chunks is returned immediately and the request that fetches the
chunks is performed in another thread. If the method or other request
properties is to be customized then set the conn parameter with a
HTTP/FTP instance that has these properties set.
If postData is non-null the method will be set to post for HTTP
requests.
The background thread will buffer up to transmitBuffers number of chunks
before is stops receiving data from network. When the main thread reads the
chunks from the range it frees up buffers and allows for the background
thread to receive more data from the network.
If no data is available and the main thread access the range it will block
until data becomes available. An exception to this is the wait(Duration)
method on the AsyncChunkInputRange
. This method will wait at maximum for the specified
duration and return true if data is available.
import std.net.curl, std.stdio; // Get some pages in the background auto range1 = byChunkAsync("www.google.com", 100); auto range2 = byChunkAsync("www.wikipedia.org"); foreach (chunk; byChunkAsync("dlang.org")) writeln(chunk); // chunk is ubyte[100] // Chunks already fetched in the background and ready foreach (chunk; range1) writeln(chunk); foreach (chunk; range2) writeln(chunk);
import std.net.curl, std.stdio; // Get a line in a background thread and wait in // main thread for 2 seconds for it to arrive. auto range3 = byChunkAsync("dlang.com", 10); if (range.wait(dur!"seconds"(2))) writeln(range.front); else writeln("No chunk received after 2 seconds!");
const(char)[] url | The url to receive content from |
const(PostUnit)[] postData | Data to HTTP Post |
size_t chunkSize | The size of the chunks |
size_t transmitBuffers | The number of chunks buffered asynchronously |
Conn conn | The connection to use e.g. HTTP or FTP. |
HTTP client functionality.
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(); // Put with data senders auto msg = "Hello world"; http.contentLength = msg.length; http.onSend = (void[] data) { auto m = cast(void[])msg; size_t len = m.length > data.length ? data.length : m.length; if (len == 0) return len; data[0..len] = m[0..len]; msg = msg[len..$]; return len; }; http.perform(); // Track progress http.method = HTTP.Method.get; http.url = "http://upload.wikimedia.org/wikipedia/commons/" "5/53/Wikipedia-logo-en-big.png"; http.onReceive = (ubyte[] data) { return data.length; }; http.onProgress = (double dltotal, double dlnow, double ultotal, double ulnow) { writeln("Progress ", dltotal, ", ", dlnow, ", ", ultotal, ", ", ulnow); return 0; }; http.perform();
Authentication method equal to etc.c.curl.CurlAuth
Time condition enumeration as an alias of etc.c.curl.CurlTimeCond
Constructor taking the url as parameter.
Perform a http request.
After the HTTP client has been setup and possibly assigned callbacks the perform() method will start performing the request towards the specified server.
The URL to specify the location of the resource.
Clear all outgoing headers.
Add a header e.g. "X-CustomField: Something is fishy".
There is no remove header functionality. Do a clearRequestHeaders and set the needed headers instead.
import std.net.curl; auto client = HTTP(); client.addRequestHeader("X-Custom-ABC", "This is the custom value"); string content = get("dlang.org", client);
The headers read from a successful response.
HTTP method used.
HTTP status line of last response. One call to perform may result in several requests because of redirection.
Set a file path to where a cookie jar should be read/stored.
Flush cookie jar to disk.
Clear session cookies.
Clear all cookies.
Set time condition on the request.
HTTP.TimeCond cond | CurlTimeCond.{none,ifmodsince,ifunmodsince,lastmod} |
SysTime timestamp | Timestamp for the condition
RFC2616 Section 14.25 |
Specifying data to post when not using the onSend callback.
The data is NOT copied by the library. Content-Type will default to application/octet-stream. Data is not converted or encoded by this method.
import std.net.curl, std.stdio; auto http = HTTP("http://www.mydomain.com"); http.onReceive = (ubyte[] data) { writeln(to!(const(char)[])(data)); return data.length; }; http.postData = [1,2,3,4,5]; http.perform();
Specifying data to post when not using the onSend callback.
The data is NOT copied by the library. Content-Type will default to text/plain. Data is not converted or encoded by this method.
import std.net.curl, std.stdio; auto http = HTTP("http://www.mydomain.com"); http.onReceive = (ubyte[] data) { writeln(to!(const(char)[])(data)); return data.length; }; http.postData = "The quick...."; http.perform();
Set the event handler that receives incoming headers.
The callback will receive a header field key, value as parameter. The const(char)[] arrays are not valid after the delegate has returned.
import std.net.curl, std.stdio; auto http = HTTP("dlang.org"); http.onReceive = (ubyte[] data) { writeln(to!(const(char)[])(data)); return data.length; }; http.onReceiveHeader = (in char[] key, in char[] value) { writeln(key, " = ", value); }; http.perform();
Callback for each received StatusLine.
Notice that several callbacks can be done for each call to perform() due to redirections.
The content length in bytes when using request that has content e.g. POST/PUT and not using chunked transfer. Is set as the "Content-Length" header. Set to size_t.max to reset to chunked transfer.
Authentication method as specified in AuthMethod .
Set max allowed redirections using the location header. uint.max for infinite.
HTTP status line ie. the first line returned in an HTTP response.
If authentication or redirections are done then the status will be for the last response received.
Major HTTP version ie. 1 in HTTP/1.0.
Minor HTTP version ie. 0 in HTTP/1.0.
HTTP status line code e.g. 200.
HTTP status line reason string.
Reset this status line
FTP access to the specified url.
Performs the ftp request as it has been configured.
After a FTP client has been setup and possibly assigned callbacks the perform() method will start performing the actual communication with the server.
The URL to specify the location of the resource.
Clear all commands send to ftp server.
Add a command to send to ftp server.
There is no remove command functionality. Do a clearCommands and set the needed commands instead.
import std.net.curl; auto client = FTP(); client.addCommand("RNFR my_file.txt"); client.addCommand("RNTO my_renamed_file.txt"); upload("my_file.txt", "ftp.digitalmars.com", client);
The content length in bytes of the ftp data.
Basic SMTP protocol support.
import std.net.curl; // Send an email with SMTPS auto smtp = SMTP("smtps://smtp.gmail.com"); smtp.setAuthentication("from.addr@gmail.com", "password"); smtp.mailTo = ["<to.addr@gmail.com>"]; smtp.mailFrom = "<from.addr@gmail.com>"; smtp.message = "Example Message"; smtp.perform();
Sets to the URL of the SMTP server.
Performs the request as configured.
The URL to specify the location of the resource.
Setter for the sender's email address.
Setter for the recipient email addresses.
Sets the message body text.
Exception thrown on errors in std.net.curl functions.
string msg | The message for the exception. |
string file | The file where the exception occurred. |
size_t line | The line number where the exception occurred. |
Throwable next | The previous exception in the chain of exceptions, if any. |
Exception thrown on timeout errors in std.net.curl functions.
string msg | The message for the exception. |
string file | The file where the exception occurred. |
size_t line | The line number where the exception occurred. |
Throwable next | The previous exception in the chain of exceptions, if any. |
Equal to etc.c.curl.CURLcode
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.
Initialize the instance by creating a working curl handle.
Duplicate this handle.
The new handle will have all options set as the one it was duplicated from. An exception to this is that all options that cannot be shared across threads are reset thereby making it safe to use the duplicate in a new thread.
Stop and invalidate this curl instance.
Pausing and continuing transfers.
Set a string curl option.
CurlOption option | A etc.c.curl.CurlOption as found in the curl documentation |
const(char)[] value | The string |
Set a long curl option.
CurlOption option | A etc.c.curl.CurlOption as found in the curl documentation |
long value | The long |
Set a void* curl option.
CurlOption option | A etc.c.curl.CurlOption as found in the curl documentation |
void* value | The pointer |
Clear a pointer option.
CurlOption option | A etc.c.curl.CurlOption as found in the curl documentation |
perform the curl request by doing the HTTP,FTP etc. as it has been setup beforehand.
The event handler that receives incoming data.
size_t delegate(InData) callback | the callback that receives the ubyte[] data. Be sure to copy the incoming data and not store a slice. |
import std.net.curl, std.stdio; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); curl.onReceive = (ubyte[] data) { writeln("Got data", to!(const(char)[])(data)); return data.length;}; curl.perform();
The event handler that receives incoming headers for protocols that uses headers.
void delegate(in char[]) callback | the callback that receives the header string. Make sure the callback copies the incoming params if it needs to store it because they are references into the backend and may very likely change. |
import std.net.curl, std.stdio; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); curl.onReceiveHeader = (in char[] header) { writeln(header); }; curl.perform();
The event handler that gets called when data is needed for sending.
size_t delegate(OutData) callback | the callback that has a void[] buffer to be filled |
import std.net.curl; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); string msg = "Hello world"; curl.onSend = (void[] data) { auto m = cast(void[])msg; size_t length = m.length > data.length ? data.length : m.length; if (length == 0) return 0; data[0..length] = m[0..length]; msg = msg[length..$]; return length; }; curl.perform();
The event handler that gets called when the curl backend needs to seek the data to be sent.
CurlSeek delegate(long, CurlSeekPos) callback | the callback that receives a seek offset and a seek position etc.c.curl.CurlSeekPos |
import std.net.curl; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); curl.onSeek = (long p, CurlSeekPos sp) { return CurlSeek.cantseek; }; curl.perform();
The event handler that gets called when the net socket has been created but a connect() call has not yet been done. This makes it possible to set misc. socket options.
int delegate(curl_socket_t, CurlSockType) callback | the callback that receives the socket and socket type etc.c.curl.CurlSockType |
import std.net.curl; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); curl.onSocketOption = delegate int(curl_socket_t s, CurlSockType t) { /+ do stuff +/ }; curl.perform();
The event handler that gets called to inform of upload/download progress.
int delegate(size_t dlTotal, size_t dlNow, size_t ulTotal, size_t ulNow) callback | the callback that receives the (total bytes to download, currently downloaded bytes, total bytes to upload, currently uploaded bytes). |
import std.net.curl; Curl curl; curl.initialize(); curl.set(CurlOption.url, "http://dlang.org"); curl.onProgress = delegate int(size_t dltotal, size_t dlnow, size_t ultotal, size_t uln) { writeln("Progress: downloaded bytes ", dlnow, " of ", dltotal); writeln("Progress: uploaded bytes ", ulnow, " of ", ultotal); curl.perform(); };