diff options
Diffstat (limited to 'manual/gun.md')
| -rw-r--r-- | manual/gun.md | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/manual/gun.md b/manual/gun.md deleted file mode 100644 index 611abf0..0000000 --- a/manual/gun.md +++ /dev/null @@ -1,340 +0,0 @@ -gun -=== - -The `gun` module provides an asynchronous interface for -connecting and communicating with Web servers over SPDY, -HTTP or Websocket. - -Types ------ - -### opts() = [{keepalive, pos_integer()} - | {retry, non_neg_integer()} - | {retry_timeout, pos_integer()} - | {type, ssl | tcp | tcp_spdy}]. - -> Configuration for the connection. - -Option descriptions -------------------- - -The default value is given next to the option name. - - - keepalive (5000) - - Time between pings in milliseconds. - - retry (5) - - Number of times Gun will try to reconnect on failure before giving up. - - retry_timeout (5000) - - Time between retries in milliseconds. - - type (ssl) - - Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP. - -Messages --------- - -Calling functions from this module may result in the following -messages being sent. - -### {gun_push, ServerPid, StreamRef, AssocToStreamRef, - Method, Host, Path, Headers} - -> Types: -> * ServerPid = pid() -> * StreamRef = AssocToStreamRef = reference() -> * Method = binary() -> * Host = binary() -> * Path = binary() -> * Headers = [{binary(), binary()}] -> -> A resource pushed alongside an HTTP response. - -### {gun_response, ServerPid, StreamRef, IsFin, Status, Headers} - -> Types: -> * ServerPid = pid() -> * StreamRef = reference() -> * IsFin = fin | nofin -> * Status = binary() -> * Headers = [{binary(), binary()}] -> -> A response to an HTTP request. - -### {gun_data, ServerPid, StreamRef, IsFin, Data} - -> Types: -> * ServerPid = pid() -> * StreamRef = reference() -> * IsFin = fin | nofin -> * Data = binary() -> -> Data associated with a response or pushed resource. - -### {gun_error, ServerPid, StreamRef, Reason} - -> Types: -> * ServerPid = pid() -> * StreamRef = reference() -> * Reason = any() -> -> An error specific to a particular stream. - -### {gun_error, ServerPid, Reason} - -> Types: -> * ServerPid = pid() -> * Reason = any() -> -> A general error. - -### {gun_ws_upgrade, ServerPid, ok} - -> Types: -> * ServerPid = pid() -> -> Websocket upgrade success. - -### {gun_ws_upgrade, ServerPid, error, IsFin, Status, Headers} - -> Types: -> * ServerPid = pid() -> * IsFin = fin | nofin -> * Status = binary() -> * Headers = [{binary(), binary()}] -> -> Websocket upgrade failure, with the HTTP response received. - -### {gun_ws, ServerPid, Frame} - -> Types: -> * ServerPid = pid() -> * Frame = ws_frame() -> -> A Websocket frame just received. - -Exports -------- - -### open(Host, Port) -> open(Host, Port, []) -### open(Host, Port, Opts) -> {ok, ServerPid} | {error, any()} - -> Types: -> * Host = inet:hostname() -> * Port = inet:port_number() -> * Opts = opts() -> * ServerPid = pid() -> -> Open a connection to the given host. - -### close(ServerPid) -> ok - -> Types: -> * ServerPid = pid() -> -> Brutally close the connection. - -### shutdown(ServerPid) -> ok - -> Types: -> * ServerPid = pid() -> -> Gracefully close the connection. -> -> A monitor can be used to be notified when the connection is -> effectively closed. - -### delete(ServerPid, Path) -> delete(ServerPid, Path, []) -### delete(ServerPid, Path, Headers) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> -> Delete a resource. - -### get(ServerPid, Path) -> get(ServerPid, Path, []) -### get(ServerPid, Path, Headers) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> -> Fetch a resource. - -### head(ServerPid, Path) -> head(ServerPid, Path, []) -### head(ServerPid, Path, Headers) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> -> Fetch a resource's headers. -> -> The server will not send the resource content, only headers. - -### options(ServerPid, Path) -> options(ServerPid, Path, []) -### options(ServerPid, Path, Headers) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> -> Obtain information about the capabilities of the server or a resource. -> -> The special path "*" can be used to obtain information about -> the server as a whole. Any other path will return information -> about the resource only. - -### patch(ServerPid, Path, Headers) -> StreamRef -### patch(ServerPid, Path, Headers, Body) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> * Body = iodata() -> -> Partially update a resource. -> -> Always set the content-type header so that Gun and the server -> can be made aware that a body is going to be sent. Also try -> to set the content-length header when possible. -> -> If a body is given, even an empty one, it is expected to be -> the full resource. -> -> If not, Gun will assume there is no body if content-type -> isn't set, and otherwise will expect you to stream the body. - -### post(ServerPid, Path, Headers) -> StreamRef -### post(ServerPid, Path, Headers, Body) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> * Body = iodata() -> -> Create or update a resource. -> -> The resource may be created at a different URL than the one -> given. -> -> Always set the content-type header so that Gun and the server -> can be made aware that a body is going to be sent. Also try -> to set the content-length header when possible. -> -> If a body is given, even an empty one, it is expected to be -> the full resource. -> -> If not, Gun will assume there is no body if content-type -> isn't set, and otherwise will expect you to stream the body. - -### put(ServerPid, Path, Headers) -> StreamRef -### put(ServerPid, Path, Headers, Body) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> * Body = iodata() -> -> Create or update a resource. -> -> The resource will be created at this exact URL. -> -> Always set the content-type header so that Gun and the server -> can be made aware that a body is going to be sent. Also try -> to set the content-length header when possible. -> -> If a body is given, even an empty one, it is expected to be -> the full resource. -> -> If not, Gun will assume there is no body if content-type -> isn't set, and otherwise will expect you to stream the body. - -### request(ServerPid, Method, Path, Headers) -> StreamRef -### request(ServerPid, Method, Path, Headers, Body) -> StreamRef - -> Types: -> * ServerPid = pid() -> * Method = iodata() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> * StreamRef = reference() -> * Body = iodata() -> -> Perform the given request on a resource. -> -> This is a general purpose function that should only be used -> when no other function can be used. -> -> Method names are case sensitive. -> -> Always set the content-type header so that Gun and the server -> can be made aware that a body is going to be sent. Also try -> to set the content-length header when possible. -> -> If a body is given, even an empty one, it is expected to be -> the full resource. -> -> If not, Gun will assume there is no body if content-type -> isn't set, and otherwise will expect you to stream the body. - -### data(ServerPid, StreamRef, IsFin, Data) -> ok - -> Types: -> * ServerPid = pid() -> * StreamRef = reference() -> * IsFin = fin | nofin -> * Data = iodata() -> -> Stream data. -> -> The `StreamRef` argument is the one returned by any of the -> request functions beforehand and uniquely identifies a request. -> -> Use `nofin` for all chunks except the last which should be `fin`. -> The last chunk may be empty. - -### cancel(ServerPid, StreamRef) -> ok - -> Types: -> * ServerPid = pid() -> * StreamRef = reference() -> -> Cancel the given stream. -> -> The `StreamRef` argument is the one returned by any of the -> request functions beforehand and uniquely identifies a request. -> -> This function will do a best effort at canceling the stream, -> depending on the capabilities of the protocol. - -### ws_upgrade(ServerPid, Path) -> ws_upgrade(ServerPid, Path, []) -### ws_upgrade(ServerPid, Path, Headers) -> ok - -> Types: -> * ServerPid = pid() -> * Path = iodata() -> * Headers = [{binary(), iodata()}] -> -> Upgrade the connection to Websocket. - -### ws_send(ServerPid, Frames) -> ok - -> Types: -> * ServerPid = pid() -> * Frames = ws_frame() | [ws_frame()] -> -> Send a Websocket frame. |