share/doc/idl/httpout.idl

/*
\file
\brief silence !
*/

typedef char *DOMString;

/*!

\defgroup httpout_grp JS HTTP output API
\ingroup jsapi_grp
\brief JavaScript API for httpout filter.

This section documents the JavaScript API available for implementing your own logic in GPAC HTTP server.

The logic is enabled using the option `js` option of the httpout filter :
```
gpac httpout:js=myserv.js vout
```

The loaded JavaScript context has all JS modules available in GPAC, except WebGL. 

It is also possible to bind the logic from a JSFilterSession using JSFSFilter.bind
@{

*/

/*! global context property representing the one and only JSHTTPServer object attached to the loaded script*/
attribute JSHTTPServer httpout;

/*!\brief JSHTTPServer API

The JSHTTPServer interface has a single instance exposed to the script under the name "httpout".
It implements callbacks from the HTTP server .
The object can also be bound to a running filter using JSFSFilter.bind
*/
interface JSHTTPServer {

/*! indicate a new request is being processed

The request is pending until the send method is used (can be asynchronous)

\note this function is mandatory
\param req the request being processed
*/
attribute void on_request(JSHTTPRequest req);
};


/*!\brief JSHTTPRequest API

The JSHTTPRequest object provides an interface to the HTTP request being processed.
*/
interface JSHTTPRequest {

/*! send the response to the request*/
attribute void send();

/*! HTTP reply code to use. If 0, the request is handled by GPAC as usual. Otherwise, the request is handled by your script if the reply does not indicate an error*/
attribute unsigned long reply;

/*! HTTP method of the request */
attribute readonly DOMString method;

/*! HTTP URL of the request */
attribute readonly DOMString url;

/*! Authentication reply code - requests are pre-identified using GPAC credentials: a value of 401 indicates no identification, 200 indicates identification OK, 403 indicates failure */
attribute readonly unsigned long auth_code;

/*! HTTP headers of the request, array of JSHTTPHeader objects*/
attribute readonly Array headers_in;

/*! HTTP headers to set on the response, array of JSHTTPHeader objects (initialized as empty)*/
attribute Array headers_out;

/*! reply body. It is undefined by default
 - if reply is 0, this can be set to a file path to serve. If not set, usual URL resolving of httpout is done
 - if reply is not 0, this can be set to a string containing the body. To deliver a binary file or a large file, use the read function
*/
attribute DOMString body


/*! callback function used to throttle the download, can be used even if the request is handled by gpac. It is set to null by default
\param done amount of bytes already sent in request
\param total total amount of bytes in request
\return a delay for next send in milliseconds
*/
attribute signed long throttle(unsigned long long done, unsigned long long total);

/*! callback function used to get data (GET requests). It is set to null by default
\param buffer array buffer to fill (shared array, do NOT keep)
\return the number of bytes read, negative value means no data available yet, 0 means end of file
*/
attribute signed long read(ArrayBuffer buffer);

/*! callback function used to receive data (PUT/POST requests). It is set to null by default
\param buffer array buffer received. If null, end of stream is reached
*/
attribute void write(ArrayBuffer buffer);

/*! callback function used to monitor end of session. It is set to null by default
\param error GPAC error code for the session. If 1 (GF_EOS), the session is ended but underlying network is kept alive, otherwise session is destroyed
*/
attribute void close(unsigned long error);


};

/*!\brief JSHTTPHeader Object

The JSHTTPHeader object provides a description of a n HTTP header.
*/
interface JSHTTPHeader {

/*! header name */
attribute readonly DOMString name;

/*! header value */
attribute readonly DOMString value;
};



/*! @} */