From 30dd46d5ac286a5aa39ff38546b72170e7dbfbb2 Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Wed, 8 Jun 2011 11:21:32 +0200 Subject: Clients started stand-alone not properly handled. OTP-9365 --- lib/inets/doc/src/httpc.xml | 180 ++++++++++++++++++++++---------------------- lib/inets/doc/src/notes.xml | 8 ++ 2 files changed, 97 insertions(+), 91 deletions(-) diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index f6b6827e93..d1671ac9bd 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -144,7 +144,7 @@ filename() = string() Result = {status_line(), headers(), Body} | {status_code(), Body} | request_id() Body = string() | binary() - Profile = profile() + Profile = profile() | pid() (when started stand_alone) Reason = term() @@ -194,16 +194,16 @@ filename() = string() Result = {status_line(), headers(), Body} | {status_code(), Body} | request_id() Body = string() | binary() - Profile = profile() + Profile = profile() | pid() (when started stand_alone) Reason = {connect_failed, term()} | {send_failed, term()} | term()

Sends a HTTP-request. The function can be both synchronous - and asynchronous. In the later case the function will return - {ok, RequestId} and later on the information will be delivered - to the receiver depending on that value.

+ and asynchronous. In the later case the function will return + {ok, RequestId} and later on the information will be delivered + to the receiver depending on that value.

Http option (http_option()) details:

@@ -211,7 +211,7 @@ filename() = string()

Timeout time for the request.

The clock starts ticking as soon as the request has been - sent.

+ sent.

Time is in milliseconds.

Defaults to infinity.

@@ -219,7 +219,7 @@ filename() = string()

Connection timeout time, used during the initial request, - when the client is connecting to the server.

+ when the client is connecting to the server.

Time is in milliseconds.

Defaults to the value of the timeout option.

@@ -227,60 +227,61 @@ filename() = string()

This is the default ssl config option, currently defaults to - essl, see below.

+ essl, see below.

Defaults to [].

If using the OpenSSL based (old) implementation of SSL, - these SSL-specific options are used.

+ these SSL-specific options are used.

Defaults to [].

If using the Erlang based (new) implementation of SSL, - these SSL-specific options are used.

+ these SSL-specific options are used.

Defaults to [].

-

Should the client automatically retrieve the information - from the new URI and return that as the result instead - of a 30X-result code.

-

Note that for some 30X-result codes automatic redirect - is not allowed. In these cases the 30X-result will always - be returned.

-

Defaults to true.

+

Should the client automatically retrieve the information + from the new URI and return that as the result instead + of a 30X-result code.

+

Note that for some 30X-result codes automatic redirect + is not allowed. In these cases the 30X-result will always + be returned.

+

Defaults to true.

A proxy-authorization header using the provided user name and - password will be added to the request.

+ password will be added to the request.

Can be used to make the client act as an HTTP/1.0 or - HTTP/0.9 client. By default this is an HTTP/1.1 - client. When using HTTP/1.0 persistent connections will - not be used.

-

Defaults to the string "HTTP/1.1".

+ HTTP/0.9 client. By default this is an HTTP/1.1 + client. When using HTTP/1.0 persistent connections will + not be used.

+

Defaults to the string "HTTP/1.1".

-

If set to true workarounds for known server deviations from - the HTTP-standard are enabled.

+

If set to true workarounds for known server deviations + from the HTTP-standard are enabled.

Defaults to false.

-

Will apply Percent-encoding, also known as URL encoding on the URL.

+

Will apply Percent-encoding, also known as URL encoding on the + URL.

Defaults to false.

@@ -296,77 +297,77 @@ filename() = string()

Streams the body of a 200 or 206 response to the calling - process or to a file. When streaming to the calling process - using the option self the following stream messages - will be sent to that process: {http, {RequestId, - stream_start, Headers}, {http, {RequestId, stream, - BinBodyPart}, {http, {RequestId, stream_end, Headers}. When - streaming to to the calling processes using the option - {self, once} the first message will have an additional - element e.i. {http, {RequestId, stream_start, Headers, Pid}, - this is the process id that should be used as an argument to - http:stream_next/1 to trigger the next message to be sent to - the calling process.

+ process or to a file. When streaming to the calling process + using the option self the following stream messages + will be sent to that process: {http, {RequestId, + stream_start, Headers}, {http, {RequestId, stream, + BinBodyPart}, {http, {RequestId, stream_end, Headers}. When + streaming to to the calling processes using the option + {self, once} the first message will have an additional + element e.i. {http, {RequestId, stream_start, Headers, Pid}, + this is the process id that should be used as an argument to + http:stream_next/1 to trigger the next message to be sent to + the calling process.

Note that it is possible that chunked encoding will add - headers so that there are more headers in the stream_end - message than in the stream_start. - When streaming to a file and the request is asynchronous the - message {http, {RequestId, saved_to_file}} will be sent.

+ headers so that there are more headers in the stream_end + message than in the stream_start. + When streaming to a file and the request is asynchronous the + message {http, {RequestId, saved_to_file}} will be sent.

Defaults to none.

Defines if the body shall be delivered as a string or as a - binary. This option is only valid for the synchronous - request.

+ binary. This option is only valid for the synchronous + request.

Defaults to string.

Should a "full result" be returned to the caller (that is, - the body, the headers and the entire status-line) or not - (the body and the status code).

+ the body, the headers and the entire status-line) or not + (the body and the status code).

Defaults to true.

Shall the headers provided by the user be made - lower case or be regarded as case sensitive.

+ lower case or be regarded as case sensitive.

Note that the http standard requires them to be - case insenstive. This feature should only be used if there is - no other way to communicate with the server or for testing - purpose. Also note that when this option is used no headers - will be automatically added, all necessary headers have to be - provided by the user.

-

Defaults to false.

+ case insenstive. This feature should only be used if there is + no other way to communicate with the server or for testing + purpose. Also note that when this option is used no headers + will be automatically added, all necessary headers have to be + provided by the user.

+

Defaults to false.

Socket options to be used for this and subsequent - request(s).

-

Overrides any value set by the - set_options - function.

+ request(s).

+

Overrides any value set by the + set_options + function.

Note that the validity of the options are not - checked in any way.

+ checked in any way.

Note that this may change the socket behaviour - (see inet:setopts/2) - for an already existing one, and therefore an already connected - request handler.

+ (see inet:setopts/2) + for an already existing one, and therefore an already connected + request handler.

By default the socket options set by the - set_options/1,2 - function are used when establishing a connection.

+ set_options/1,2 + function are used when establishing a connection.

Defines how the client will deliver the result of an - asynchroneous request (sync has the value - false).

+ asynchroneous request (sync has the value + false).

@@ -380,7 +381,7 @@ filename() = string()

Information will be delivered to the receiver via calls - to the provided fun:

+ to the provided fun: 

 Receiver(ReplyInfo)
@@ -389,7 +390,7 @@ Receiver(ReplyInfo)

Information will be delivered to the receiver via calls - to the callback function:

+ to the callback function: 

 apply(Module, Function, [ReplyInfo | Args])
@@ -410,7 +411,7 @@ apply(Module, Function, [ReplyInfo | Args])

Defaults to the pid() of the process calling the request - function (self()).

+ function (self()).

@@ -425,7 +426,7 @@ apply(Module, Function, [ReplyInfo | Args]) RequestId = request_id() - A unique identifier as returned by request/4 - Profile = profile() + Profile = profile() | pid() (when started stand_alone)

Cancels an asynchronous HTTP-request.

@@ -514,11 +515,10 @@ apply(Module, Function, [ReplyInfo | Args]) This option is used to switch on (or off) different levels of erlang trace on the client. It is a debug feature. - Profile = profile() + Profile = profile() | pid() (when started stand_alone) -

Sets options to be used for subsequent - requests.

+

Sets options to be used for subsequent requests.

If possible the client will keep its connections alive and use persistent connections @@ -548,7 +548,7 @@ apply(Module, Function, [ReplyInfo | Args])

Triggers the next message to be streamed, e.i. - same behavior as active once for sockets.

+ same behavior as active once for sockets.

@@ -562,14 +562,14 @@ apply(Module, Function, [ReplyInfo | Args]) SetCookieHeaders = headers() - where field = "set-cookie" Url = url() - Profile = profile() + Profile = profile() | pid() (when started stand_alone)

Saves the cookies defined in SetCookieHeaders - in the client profile's cookie database. You need to - call this function if you have set the option cookies to verify. - If no profile is specified the default profile will be used. -

+ in the client profile's cookie database. You need to + call this function if you have set the option cookies + to verify. + If no profile is specified the default profile will be used.

@@ -582,13 +582,12 @@ apply(Module, Function, [ReplyInfo | Args]) making a request to Url using the profile Profile. Url = url() - Profile = profile() + Profile = profile() | pid() (when started stand_alone)

Returns the cookie header that would be sent - when making a request to Url using the profile Profile. - If no profile is specified the default profile will be used. -

+ when making a request to Url using the profile Profile. + If no profile is specified the default profile will be used.

@@ -600,12 +599,12 @@ apply(Module, Function, [ReplyInfo | Args]) reset_cookies(Profile) -> void() Reset the cookie database. - Profile = profile() + Profile = profile() | pid() (when started stand_alone) -

Resets (clears) the cookie database for the specified Profile. - If no profile is specified the default profile will be used. -

+

Resets (clears) the cookie database for the specified + Profile. If no profile is specified the default profile + will be used.

@@ -615,17 +614,16 @@ apply(Module, Function, [ReplyInfo | Args]) which_cookies(Profile) -> cookies() Dumps out the entire cookie database. - Profile = profile() - cookies() = [cooie_stores()] - cookie_stores() = {cookies, icookies()} | {session_cookies, icookies()} - icookies() = [icookie()] + Profile = profile() | pid() (when started stand_alone) + cookies() = [cookie_stores()] + cookie_stores() = {cookies, cookies()} | {session_cookies, cookies()} + cookies() = [cookie()] cookie() = term()

This function produces a list of the entire cookie database. - It is intended for debugging/testing purposes. - If no profile is specified the default profile will be used. -

+ It is intended for debugging/testing purposes. + If no profile is specified the default profile will be used.

diff --git a/lib/inets/doc/src/notes.xml b/lib/inets/doc/src/notes.xml index ed1b974771..df0b10ef58 100644 --- a/lib/inets/doc/src/notes.xml +++ b/lib/inets/doc/src/notes.xml @@ -65,6 +65,14 @@

Own Id: OTP-5566

 + +

[httpc] Clients started stand-alone not properly handled. + Also it was not documented how to use them, that is that + once started, they are represented by a pid() and not by + their profile().

+

Own Id: OTP-9365

+ + -- cgit v1.2.3