Project

General

Profile

Scol standard library package  0.3.1
Common and usefull functions for all Scol applications
The network API based on the legacy Scol API.

Functions

 std_httpAddUrl (o, p)
 Add an url / header / data to send.
 std_httpAddUrlOnly (o, szUrl)
 Add an url only, without header nor data to send. These two last parameters will be nil, thus, this conivience function should be use to a GET request only.
 std_httpGetCallbacks (o)
 Return the current callbacks, defined in a persistent request object.
 std_httpGetContinueAll (o)
 Return if all urls should be processed one by one (1) or not (0).
 std_httpGetEnsabled (o)
 Return if a request object is enabled (1) or disabled (0)
 std_httpGetLastObject ()
 Return the last request object added.
 std_httpGetObjects ()
 Return all request objects.
 std_httpGetPersistent (o)
 Return if a request object is persistent (1) or not (0)
 std_httpGetRemoveInSuccess (o)
 Return if urls should be removed if the process is a success.
 std_httpGetSimple (szUrl, cbOk, cbCur, cbError)
 GET http asynchronous request.
 std_httpGetTest ()
 Return the current url to test the connection.
 std_httpGetTestConection (o)
 Return if the connection must be testes before each request or not.
 std_httpGetUrl (o)
 Return the current url, defined in a request object.
 std_httpGetVerb (o)
 Return the verb to the given request object.
 std_httpNew (szUrl)
 Create a new persistent request object.
 std_httpRun (o)
 Run the process according to the choosen parameters (see others functions in this API)
 std_httpSetCallbacks (o, cbOk, cbCur, cbError)
 Set the callbacks to a persistent request object.
 std_httpSetContinueAll (o, state)
 Set if the all urls should be processed one by one (1) or not (0). If 0, std_httpRun should be called manually after each previous result.
 std_httpSetEnabled (o, state)
 Set if a request object is enabled or disabled.
 std_httpSetRemoveInSuccess (o, state)
 Set if the urls should be removed in the list if the end of the request is a success.
 std_httpSetTest (szUrl)
 Set the url to test the connection.
 std_httpSetTestConection (o, state)
 Set if the connection must be testes before each request or not. This is helpful in a local request for example.
 std_httpSetUrl (o, lUrl)
 Set the urls / headers / datas to send.
 std_httpSetVerb (o, szVerb)
 Set the verb to the all process in this object.
 std_httpSupportedVerb ()
 Return a list of supported request (GET, POST, ...)

Detailed Description

Package to load : lib/std/http.pkg

This API provides some options to write HTTP client request routines for Scol. This is older than the Libcurl API ( lib/std/curl.pkg ).

Dependancies :

This API uses the legacy INET Scol API.

Function Documentation

std_httpGetSimple ( szUrl  ,
cbOk  ,
cbCur  ,
cbError   
)

GET http asynchronous request.

Prototype : fun [S fun [STD_HTTP_CLIENT S] I fun [STD_HTTP_CLIENT I] I fun [STD_HTTP_CLIENT I] I] STD_HTTP_CLIENT

Parameters
S: url to get
fun[STD_HTTP_CLIENT S] I : function to call when the response is whole. The string argument is the datas received from the server.
fun[STD_HTTP_CLIENT I] I : function to call when a part of the response is received. The integer argument is the size of this part.
fun[STD_HTTP_CLIENT I] I : function to call when an error occurs (and when the response is complete). The integer argument is a following value.
  • STD_HTTPSUCCESS : request finished with success
  • STD_HTTPERRUNKNOWN : internal and undefined error, nothing to do ...
  • STD_HTTPNOTCONNECTED : client is not connected or the connection fails. Check this ...
  • STD_HTTPDISABLED : the request object has been disabled
  • STD_HTTPSTILLENBLED : the request can not be stopped because it is still enabled
  • STD_HTTPCANCELLED : the request has been cancelled
Returns
STD_HTTP_CLIENT : the new request object
std_httpNew ( szUrl  )

Create a new persistent request object.

A such object can be prepared and reused. By default, it is enabled and persistent. No callback are defined by default.

Prototype : fun [S] STD_HTTP_CLIENT

Parameters
S: an url (can be nil)
Returns
STD_HTTP_CLIENT : this new object.
See Also
std_httpDownload to perform a simple download
std_httpSetCallbacks to add callbacks
std_httpSetUrl to change the url
std_httpSetVerb to define the request type
std_httpSetUrl ( ,
lUrl   
)

Set the urls / headers / datas to send.

Prototype : fun [STD_HTTP_CLIENT [S r1]] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
[[SS S] r1] : a list of urls/headers/datas to send, headers and datas should be nil if the used verb is GET.
Remarks
The last added element will be the first processed element.
Returns
STD_HTTP_CLIENT : the same object or nil if error (object is not valid)
Remarks
this set doesn't change anything to the current operation, if any.
std_httpAddUrl ( ,
 
)

Add an url / header / data to send.

Prototype : fun [STD_HTTP_CLIENT [S S S]] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
[SS S] : an url, an header, any datas to send
Returns
STD_HTTP_CLIENT : the same object or nil if error (object is not valid)
Remarks
this set doesn't change anything to the current operation, if any.
std_httpAddUrlOnly ( ,
szUrl   
)

Add an url only, without header nor data to send. These two last parameters will be nil, thus, this conivience function should be use to a GET request only.

Prototype : fun [STD_HTTP_CLIENT S] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
S: an url
Returns
STD_HTTP_CLIENT : the same object or nil if error (object is not valid)
Remarks
this set doesn't change anything to the current operation, if any.
std_httpGetUrl ( )

Return the current url, defined in a request object.

Prototype : fun [STD_HTTP_CLIENT] [S r1]

Parameters
STD_HTTP_CLIENT: a request object
Returns
[S r1] : the urls
std_httpSetCallbacks ( ,
cbOk  ,
cbCur  ,
cbError   
)

Set the callbacks to a persistent request object.

Prototype : fun [STD_HTTP_CLIENT fun [STD_HTTP_CLIENT S] I fun [STD_HTTP_CLIENT I] fun [STD_HTTP_CLIENT I]] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
fun[STD_HTTP_CLIENT S] I : the callback (success)
fun[STD_HTTP_CLIENT I] I : the calback (ongoing)
fun[STD_HTTP_CLIENT I] I : the callback (errors)
Returns
STD_HTTP_CLIENT : the same object or nil if error (object is not valid)
std_httpGetCallbacks ( )

Return the current callbacks, defined in a persistent request object.

Prototype : fun [STD_HTTP_CLIENT] [fun [STD_HTTP_CLIENT S] I fun [STD_HTTP_CLIENT I] fun [STD_HTTP_CLIENT I]]

Parameters
STD_HTTP_CLIENT: a persistent request object
Returns
[fun [STD_HTTP_CLIENT S] I fun [STD_HTTP_CLIENT I] fun [STD_HTTP_CLIENT I]] : the three callbacks or nil if the object is invalid
std_httpSetVerb ( ,
szVerb   
)

Set the verb to the all process in this object.

Remarks
It is possible but not recommended to the beginner to change this parameter more once time
See Also
std_httpSupportedVerb

Prototype : fun [STD_HTTP_CLIENT S] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
S: a new valid verb.
Returns
STD_HTTP_CLIENT : the same object or nil if error (object not persistent or unknown verb)
std_httpGetVerb ( )

Return the verb to the given request object.

See Also
std_httpSupportedVerb

Prototype : fun [STD_HTTP_CLIENT] S

Parameters
STD_HTTP_CLIENT: a request object
Returns
S : the verb
std_httpSetEnabled ( ,
state   
)

Set if a request object is enabled or disabled.

If the request object is persistent, no operation can be done while it is disabled. If the request object is not persistent, the current operation will be stopped and destroyed if the new state is 'disabled'.

Prototype : fun [STD_HTTP_CLIENT I] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
I: a new state (1 : enabled, 0 disabled, all other values are ignored.
Returns
STD_HTTP_CLIENT : the same object
std_httpGetEnsabled ( )

Return if a request object is enabled (1) or disabled (0)

Prototype : fun [STD_HTTP_CLIENT] I

Parameters
STD_HTTP_CLIENT: a request object
Returns
I : the state
std_httpGetPersistent ( )

Return if a request object is persistent (1) or not (0)

Prototype : fun [STD_HTTP_CLIENT] I

Parameters
STD_HTTP_CLIENT: a request object
Returns
I : this state
Remarks
this parameter can't be set after its initialization.
std_httpSetRemoveInSuccess ( ,
state   
)

Set if the urls should be removed in the list if the end of the request is a success.

Prototype : fun [STD_HTTP_CLIENT I] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
I: a new state (1 : enabled (default), 0 disabled, all other values are ignored.
Returns
STD_HTTP_CLIENT : the same object or nil if the object is invalid
std_httpGetRemoveInSuccess ( )

Return if urls should be removed if the process is a success.

Prototype : fun [STD_HTTP_CLIENT] I

Parameters
STD_HTTP_CLIENT: a request object
Returns
I : this state
std_httpSetTestConection ( ,
state   
)

Set if the connection must be testes before each request or not. This is helpful in a local request for example.

Prototype : fun [STD_HTTP_CLIENT I] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
I: a new state (1 : yes (default), 0 no, all other values are ignored.
Returns
STD_HTTP_CLIENT : the same object or nil if the object is invalid
std_httpGetTestConection ( )

Return if the connection must be testes before each request or not.

Prototype : fun [STD_HTTP_CLIENT] I

Parameters
STD_HTTP_CLIENT: a request object
Returns
I : this state (1 : yes, 0 : no)
std_httpSetContinueAll ( ,
state   
)

Set if the all urls should be processed one by one (1) or not (0). If 0, std_httpRun should be called manually after each previous result.

Remarks
if state is 0 and std_httpGetRemoveInSuccess is at 0 too, the behavior can be undefined.

Prototype : fun [STD_HTTP_CLIENT I] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
I: a new state (1 : one by one, state by default, 0 disabled, all other values are ignored.
Returns
STD_HTTP_CLIENT : the same object or nil if the object is invalid
std_httpGetContinueAll ( )

Return if all urls should be processed one by one (1) or not (0).

Prototype : fun [STD_HTTP_CLIENT] I

Parameters
STD_HTTP_CLIENT: a request object
Returns
I : this state
std_httpRun ( )

Run the process according to the choosen parameters (see others functions in this API)

Prototype : fun [STD_HTTP_CLIENT] STD_HTTP_CLIENT

Parameters
STD_HTTP_CLIENT: a persistent request object
Returns
STD_HTTP_CLIENT : the same object or nil if the object is invalid
std_httpGetTest ( )

Return the current url to test the connection.

Prototype : fun [] S

Returns
S : the url
std_httpSetTest ( szUrl  )

Set the url to test the connection.

Prototype : fun [S] S

Parameters
S: an url
Returns
S : the same url or nil if error (empty url)
std_httpGetObjects ( )

Return all request objects.

Prototype : fun [] [STD_HTTP_CLIENT r1]

Returns
[STD_HTTP_CLIENT r1] : the list
std_httpGetLastObject ( )

Return the last request object added.

Prototype : fun [] STD_HTTP_CLIENT

Returns
STD_HTTP_CLIENT : this last object
std_httpSupportedVerb ( )

Return a list of supported request (GET, POST, ...)

Prototype : fun [] [S r]

Returns
[S r] : this list