WebSVN – Kolibri OS – Diff – /programs/develop/libraries/http/http_en.txt


get(*url, identifier, flags, *add_header);
	*url = pointer to ASCIIZ URL
	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
	flags = bit flags (see end of this document).
	*add_header = pointer to ASCIIZ additional header parameters, or null for none.
			Every additional parameter must end with CR LF bytes, including the last line.
Initiates a HTTP connection, using 'GET' method.
 - returns 0 on error, identifier otherwise.
 
head(*url, identifier, flags, *add_header);
	*url = pointer to ASCIIZ URL
	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
	flags = bit flags (see end of this document).
	*add_header = pointer to ASCIIZ additional header parameters, or null for none.	
			Every additional parameter must end with CR LF bytes, including the last line.	
Initiate a HTTP connection, using 'HEAD' method.
 - returns 0 on error, identifier otherwise
 
post(*url, identifier, flags, *add_header, *content-type, content-length);
	*url = pointer to ASCIIZ URL
	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
	flags = bit flags (see end of this document).
	*add_header = pointer to ASCIIZ additional header parameters, or null for none.	
			Every additional parameter must end with CR LF bytes, including the last line.
	*content-type = pointer to ASCIIZ string containing content type.
	content-length = length of the content (in bytes).
Initiate a HTTP connection, using 'POST' method.
The content itself must be send to the socket (which you can find in the structure),
using system function 75, 6.
 - returns 0 on error, identifier otherwise
 
receive(identifier);
	identifier = identifier which one of the previous functions returned
This procedure will handle all incoming data for a connection and place it in the buffer.
As long as the procedure expects more data, -1 is returned and the procedure must be called again.
 - When transfer is done, the procedure will return 0. 
The receive procedure is non-blocking by default, but can be made to block by setting FLAG_BLOCK.
 
The HTTP header is placed together with some flags and other attributes in the http_msg structure.
This structure is defined in http.inc (and not copied here because it might still change.)
The identifier used by the functions is actually a pointer to this structure.
In the dword named .flags, the library will set various bit-flags indicating the status of the process.
(When a transfer is done, one should check these bit-flags to find out if the transfer was error-free.)
The HTTP header is placed at the end of this structure. The content is placed in another buffer.
The dword .status contains the status code received from the server (e.g. 200 for OK).
In header_length you'll find the length of the header as soon as it has been received.
In content_ptr you'll find a pointer to the actual content.
In content_length you'll find the length of the content. 
In content_received, you'll find the number of content bytes already received.
 
send(identifier, *dataptr, datalength);
	identifier = identifier which one of the previous functions returned
	*dataptr = pointer to the data you want to send
	datalength = length of the data to send (in bytes)
This procedure can be used to send data to the server (POST)
 - returns number of bytes sent, -1 on error
 
 
User flags:
 
For the flag codes themselves, see http.inc file.
 
 FLAG_KEEPALIVE will keep the connection open after first GET/POST/.. so you can send a second request on the same TCP session. 
In this case, the session must be closed manually when done by using the exported disconnect() function.
 
 FLAG_STREAM will force receive() to put the received content in a series of fixed size buffers, instead of everything in one big buffer.
This can be used for example to receive an internet radio stream, 
but also to download larger files for which it does not make sense to put them completely in RAM first.
 
 FLAG_REUSE_BUFFER is to be used in combination with FLAG_STREAM and will make receive() function re-use the same buffer.
This, for example, can be used when downloading a file straight to disk.
 
 FLAG_BLOCK will make receive() function blocking. This is only to be used when receiving one file from a thread that has no other work.
If however, you want to receive multiple files, or do other things in the program mainloop, you should call the receive function periodically. 
You may use system function 10 or 23 to wait for network event before calling one or more receive() functions.


Subversion Repositories Kolibri OS

(root)/programs/develop/libraries/http/http_en.txt – Rev 5769 → 7094

Rev 5769		Rev 7094
1	get(url, identifier, flags, add_header);	1	get(url, identifier, flags, add_header);
2	*url = pointer to ASCIIZ URL	2	*url = pointer to ASCIIZ URL
3	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.	3	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
4	flags = bit flags (see end of this document).	4	flags = bit flags (see end of this document).
5	*add_header = pointer to ASCIIZ additional header parameters, or null for none.	5	*add_header = pointer to ASCIIZ additional header parameters, or null for none.
6	Every additional parameter must end with CR LF bytes, including the last line.	6	Every additional parameter must end with CR LF bytes, including the last line.
7	Initiates a HTTP connection, using 'GET' method.	7	Initiates a HTTP connection, using 'GET' method.
8	- returns 0 on error, identifier otherwise.	8	- returns 0 on error, identifier otherwise.
9		9
10	head(url, identifier, flags, add_header);	10	head(url, identifier, flags, add_header);
11	*url = pointer to ASCIIZ URL	11	*url = pointer to ASCIIZ URL
12	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.	12	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
13	flags = bit flags (see end of this document).	13	flags = bit flags (see end of this document).
14	*add_header = pointer to ASCIIZ additional header parameters, or null for none.	14	*add_header = pointer to ASCIIZ additional header parameters, or null for none.
15	Every additional parameter must end with CR LF bytes, including the last line.	15	Every additional parameter must end with CR LF bytes, including the last line.
16	Initiate a HTTP connection, using 'HEAD' method.	16	Initiate a HTTP connection, using 'HEAD' method.
17	- returns 0 on error, identifier otherwise	17	- returns 0 on error, identifier otherwise
18		18
19	post(url, identifier, flags, add_header, *content-type, content-length);	19	post(url, identifier, flags, add_header, *content-type, content-length);
20	*url = pointer to ASCIIZ URL	20	*url = pointer to ASCIIZ URL
21	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.	21	identifier = identifier of previously opened connection (keep-alive), or 0 to open a new one.
22	flags = bit flags (see end of this document).	22	flags = bit flags (see end of this document).
23	*add_header = pointer to ASCIIZ additional header parameters, or null for none.	23	*add_header = pointer to ASCIIZ additional header parameters, or null for none.
24	Every additional parameter must end with CR LF bytes, including the last line.	24	Every additional parameter must end with CR LF bytes, including the last line.
25	*content-type = pointer to ASCIIZ string containing content type.	25	*content-type = pointer to ASCIIZ string containing content type.
26	content-length = length of the content (in bytes).	26	content-length = length of the content (in bytes).
27	Initiate a HTTP connection, using 'POST' method.	27	Initiate a HTTP connection, using 'POST' method.
28	The content itself must be send to the socket (which you can find in the structure),	28	The content itself must be send to the socket (which you can find in the structure),
29	using system function 75, 6.	29	using system function 75, 6.
30	- returns 0 on error, identifier otherwise	30	- returns 0 on error, identifier otherwise
31		31
32	receive(identifier);	32	receive(identifier);
33	identifier = identifier which one of the previous functions returned	33	identifier = identifier which one of the previous functions returned
34	This procedure will handle all incoming data for a connection and place it in the buffer.	34	This procedure will handle all incoming data for a connection and place it in the buffer.
35	As long as the procedure expects more data, -1 is returned and the procedure must be called again.	35	As long as the procedure expects more data, -1 is returned and the procedure must be called again.
36	- When transfer is done, the procedure will return 0.	36	- When transfer is done, the procedure will return 0.
37	The receive procedure is non-blocking by default, but can be made to block by setting FLAG_BLOCK.	37	The receive procedure is non-blocking by default, but can be made to block by setting FLAG_BLOCK.
38		38
39	The HTTP header is placed together with some flags and other attributes in the http_msg structure.	39	The HTTP header is placed together with some flags and other attributes in the http_msg structure.
40	This structure is defined in http.inc (and not copied here because it might still change.)	40	This structure is defined in http.inc (and not copied here because it might still change.)
41	The identifier used by the functions is actually a pointer to this structure.	41	The identifier used by the functions is actually a pointer to this structure.
42	In the dword named .flags, the library will set various bit-flags indicating the status of the process.	42	In the dword named .flags, the library will set various bit-flags indicating the status of the process.
43	(When a transfer is done, one should check these bit-flags to find out if the transfer was error-free.)	43	(When a transfer is done, one should check these bit-flags to find out if the transfer was error-free.)
44	The HTTP header is placed at the end of this structure. The content is placed in another buffer.	44	The HTTP header is placed at the end of this structure. The content is placed in another buffer.
45	The dword .status contains the status code received from the server (e.g. 200 for OK).	45	The dword .status contains the status code received from the server (e.g. 200 for OK).
46	In header_length you'll find the length of the header as soon as it has been received.	46	In header_length you'll find the length of the header as soon as it has been received.
47	In content_ptr you'll find a pointer to the actual content.	47	In content_ptr you'll find a pointer to the actual content.
48	In content_length you'll find the length of the content.	48	In content_length you'll find the length of the content.
49	In content_received, you'll find the number of content bytes already received.	49	In content_received, you'll find the number of content bytes already received.
50		50
51	send(identifier, *dataptr, datalength);	51	send(identifier, *dataptr, datalength);
52	identifier = identifier which one of the previous functions returned	52	identifier = identifier which one of the previous functions returned
53	*dataptr = pointer to the data you want to send	53	*dataptr = pointer to the data you want to send
54	datalength = length of the data to send (in bytes)	54	datalength = length of the data to send (in bytes)
55	This procedure can be used to send data to the server (POST)	55	This procedure can be used to send data to the server (POST)
56	- returns number of bytes sent, -1 on error	56	- returns number of bytes sent, -1 on error
57		57
58		58
59	User flags:	59	User flags:
60		60
61	For the flag codes themselves, see http.inc file.	61	For the flag codes themselves, see http.inc file.
62		62
63	FLAG_KEEPALIVE will keep the connection open after first GET/POST/.. so you can send a second request on the same TCP session.	63	FLAG_KEEPALIVE will keep the connection open after first GET/POST/.. so you can send a second request on the same TCP session.
64	In this case, the session must be closed manually when done by using the exported disconnect() function.	64	In this case, the session must be closed manually when done by using the exported disconnect() function.
65		65
66	FLAG_STREAM will force receive() to put the received content in a series of fixed size buffers, instead of everything in one big buffer.	66	FLAG_STREAM will force receive() to put the received content in a series of fixed size buffers, instead of everything in one big buffer.
67	This can be used for example to receive an internet radio stream,	67	This can be used for example to receive an internet radio stream,
68	but also to download larger files for which it does not make sense to put them completely in RAM first.	68	but also to download larger files for which it does not make sense to put them completely in RAM first.
69		69
70	FLAG_REUSE_BUFFER is to be used in combination with FLAG_STREAM and will make receive() function re-use the same buffer.	70	FLAG_REUSE_BUFFER is to be used in combination with FLAG_STREAM and will make receive() function re-use the same buffer.
71	This, for example, can be used when downloading a file straight to disk.	71	This, for example, can be used when downloading a file straight to disk.
72		72
73	FLAG_BLOCK will make receive() function blocking. This is only to be used when receiving one file from a thread that has no other work.	73	FLAG_BLOCK will make receive() function blocking. This is only to be used when receiving one file from a thread that has no other work.
74	If however, you want to receive multiple files, or do other things in the program mainloop,	74	If however, you want to receive multiple files, or do other things in the program mainloop, you should call the receive function periodically.
75	you should use system function 10 or 23 to wait for network event before calling one or more receive() functions.	75	You may use system function 10 or 23 to wait for network event before calling one or more receive() functions.
76		76