Platform

platform.alloc_buffer(size)

Allocates size bytes of memory. Throws exception in case of error
It is ensured that a maximum of 1GB of data is allowed to be allocated
per given lua state.

Parameters:
    size : integer, requested size of memory

Return:
    buf: Pointer to allocated buffer

platform.async_run_lua_script(...);

Runs a mentioned lua script asynchronously, with the inputs provided as string arguments
to the function

The function does not return, any exception has to be managed within the script

Paramters: 
    Variable number of arguments, with atlease 1
    The first string parameter is the lua script to run
    Rest of the parametes are arguments to the script
Return:
    None

platform.async_run_lua_script_singleton(...);

Similar to platform.async_run_lua_script, except that it is ensured that a single instance
of the given script is running, i.e. if an already existing instance of the script is
currently running, another instance will not be started.

platform.close_http_connection(http_session)

Closes the session objects and the associated TCP connection

Parameters:
    http_session: Session object acquired by platform.make_http_connection
Return:
    None

platform.close_tcp_connection(tcp_conn)

Closes the given TCP connection

Parameters:
    tcp_conn: TCP connection object acquired by platform.make_tcp_connection
Return:
    None

platform.debug_ss_ptr(tcp_conn)

Prints details pertaining to TCP connection to standard output
Information printed are
    pointer to lua state,
    file descriptor of the scoket,
    if the socket fd is live

Parameters:
    tcp_conn: Socket connection pointer
Return:
    None

platform.ev_dbg_pthread_self(debug_str)

Prints the thread id of the current thread, along with an optional string argument to
standard output

Parameters:
    debug_str: Optional debug string, which will be printed along with the thread id
Return:
    None

platform.ev_hibernate(time_in_sec)

Suspends execution of a lua thread for  time_in_sec seconds
While the lua thread is put in sleep, the underlying OS thread
will process another task

Parameters:
    time_in_sec: integer number of seconds the lua thread should sleep
Return:
    None

platform.file_open()

Opens a file and returns the file handle to be used for read and write operations

Parameters:
    file_name : type string, contains the filename with path which will be opened
    open_mode : mode in which the file will be opened
        "r" : Opens the file in read-only mode
        "w" : Opens the file in write mode and positions the file pointer at the begining of file
        "a" : Opens the file in append mode (reand and write and file pointer at the end)
        "r+" : Opens the file in read-write mode with pointer at the begining
        "w+" : Opens the file in read-write mode after truncating the file, if the file does not
               exist it is created
        "a+" : Opens the file in read-write mode in append mode, if the file does not exist it
               is created
Return values
    fh : file handle using which read and write operations can be achieved
    err: In case of any error during the opening process the error is returned in the second
         return parameter while fh will have null

platform.get_acc_sock_to_be_closed()

Gets the state variable _cl_state in Accepted socket of the platform (evluaserver)

Parameters:
    None
Return:
    cl_state: boolean, true - the socket is marked for closure, false - socket is not marked
              for closure

platform.get_accepted_stream_socket()

Sets the state variable _cl_state in Accepted socket of the platform (evluaserver)

Parameters:
    cl_state: boolean, true - the socket is marked for closure, false - socket is not marked
              for closure
Return:
    None

platform.get_host_ip_address_and_port()

Gets the IP address and the port number being listened to by the current evluaserver
as configured in the properties file.

Parameters:
    None
Return:
    ip_address: string
    port: string

platform.get_http_request()

Gets the associated request object with respect to the current request processing lua state

Parameters:
    None
Return:
    request : Request object

platform.get_http_response()

Gets the associated response object with respect to the current response processing lua state

Parameters:
    None
Return:
    response : Response object

platform.get_lua_state()

Gets the pointer of lua_State * of the current coroutine for debugging purpose
Parameters:
    None
Return:
    lua_State : Pointer to lua_State of current coroutine

platform.get_sock_fd(ss)

Gets the file descriptor of the stream socket pointer
Parameters:
    ss: stream socket pointer
Return:
    fd : integer file descriptor

platform.get_socket_upgrade_to()

Gets the upgraded state of the accepted socket of the lua coroutine.

Parameters:
    None
Return:
    upg : integer, 0 - Not upgraded (still accepts HTTP 1.1 requests), 1 - Upgraded as WEBSOCKET

platform.get_ws_recvd_msg_handler()

Gets the lua file that has implemented an object with handle_message function associated with the WEBSOCKET
The handle_message function if implemented will get called upon arrival of a new WEBSOCKET message

Parameters:
    None, works on the accepted socket associated with the lua coroutine
Return:
    lua_file_name: string, lua file, that should be passed to require as an input parameter to get the handle
                    to the implementation class

platform.mail_message_funcs()

Returns the SMTP client module, which can be used to construct and send emails.

Paramters:
    None
Return:
    smtp_client : A lua module that contains the functions necessary to construct and send email.

platform.make_http_connection(server_address, port_num, [timeout])

Establishes a TCP connection and constructs a HTTP client object around the TCP connection
and returns the same

Parameters:
    server_address: string, Either IP address or URL of the server
    port_num: Interger, port number to which the connection has to be established
    timeout: Integer, optional parameter, that indicates how long to wait before giving up
Return:
    http_session: The client http session object
    ss : The underlying stream socket
ERROR:
    Throws appropriate error using perror, which can be caught using pcall or xpcall mechanism

platform.make_http_connection_secure(http_connection, ss)

Makes the established HTTP session secure
This function must be called after calling netSSL.conect_TLS on ss returned by make_http_connection

Parameters:
    http_connection: http_connection, handle to http session
    ss: Stream socket
Return:
    None
ERROR:
    Throws appropriate error using perror, which can be caught using pcall or xpcall mechanism

platform.make_tcp_connection(server_address, port_num, [timeout])

Establishes a TCP connection and constructs and returns a handle to the connection 

Parameters:
    server_address: string, Either IP address or URL of the server
    port_num: Interger, port number to which the connection has to be established
    timeout: Integer, optional parameter, that indicates how long to wait before giving up
Return:
    ss : The stream socket
ERROR:
    Throws appropriate error using perror, which can be caught using pcall or xpcall mechanism

platform.new_request()

Constructs a new HTTP request object and returns a handle to the same

Parameters:
    None
Return:
    http_req: Handle to a HTTP request object

platform.properties_funcs()

Loads a lua module containg a set of properties access functions

Parameters:
    None
Return:
    properties_funcs: A lua module with the following functions

    properties_funcs.get_bool_property(name): given the string property name, gets the boolean value

    properties_funcs.get_int_property(name): given the string property name, gets the integer value

    properties_funcs.get_string_property(name): given the string property name, gets the string value

platform.receive_http_response(http_session, [timeout])

Receives response from a HTTP server after having sent a request on the same connection.

Parameters:
    http_session: Client session established via platform.make_http_connection
    timeout: Optional, integer value, which indicates the number of seconds to wait for response to arrive

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.recv_data_from_socket(ss, buf, size, [timeout])

Interface to receive data from an opened socket connection

Parameters:
    ss: Stream socket, either accepted socket or connected socket (via platform.make_tcp_conccetion)
    buf: Memory buffer created via alloc_buffer
    size: Integer number of bytes to be received
    timeout: Optional integer, number of seconds to wait for arrival of the response
Return:
    ret: Integer, number of bytes received

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.resolve_host_address(domain_name, service_name)

Resolves the domain_name to actual list of IP addresses and corresponding port numbers using the DNS resolution protocol.

Parameters:
    domain_name: string
    service_name: string, name of the service like HTTP, HTTTP(s), SMTP, FTP etc...
Return:
    address_array: An array of resolved host addresses where each member contains { hostaddress, portnum, addrfamily }

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.send_cms_on_socket(ss, cms)

Sends data in a chunked memory stream (an efio data structure) buffer completely on an open socket

Parameters:
    ss: An open stream socket
    cms: Handle to chunked memory stream (produced for example in mail message serialization)

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.send_data_on_acc_socket(ss, buf, size)

Sends data to peer on an accepted socket instance

Parameters:
    ss: Handle to stream socket
    buf: Data buffer acquired via platform.alloc_buffer
    size: Integer, size of data to be sent
Return:
    ret: Integer, size of data sent on the socket

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.send_data_on_socket(ss, buf, size)

Sends data to peer on a  previously opened socket

Parameters:
    ss: Handle to stream socket
    buf: Data buffer acquired via platform.alloc_buffer
    size: Integer, size of data to be sent
Return:
    ret: Integer, size of data sent on the socket

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.send_request_body(http_client, request)

Asynchronously sends request body of a HTTP request (created by new_request) over an established http session

Parameters:
    http_client: handle to http session
    request: handle to request object

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.send_request_header(http_client, request)

Asynchronously sends request header of a HTTP request (created by new_request) over an established http session

Parameters:
    http_client: handle to http session
    request: handle to request object

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.set_acc_sock_to_be_closed()

Sets the _cl_state variable in the accepted socket associated with the lua thread to be true

Parameters:
    None
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.set_socket_upgrade_to()

Used to set the upgraded status of accepted socket to WEBSOCKET

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.set_ws_recvd_msg_handler()

Sets the lua file that has implemented an object with handle_message function as the associated message
handler with the WEBSOCKET
The handle_message function if implemented will get called upon arrival of a new WEBSOCKET message

Parameters:
    msg_handler: message handler lua file name (complete path)
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.shutdown_websocket(ss, type)

Closes the given websocket

Parameters:
    ss: handle to websocket
    type: Integer value, one of
          1 - Stop receiving messages on serve side (accepted) websocket
          2 - Send shutdown message to peer, Not implemented as of now.
          3 - Shut down opened websocket
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.socket_active(ss)

Establishes if the socket handle is still active

Parameters:
    ss: Handle to socket connection
Return:
    status: true if active, false if not active

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.stop_taking_requests()

Upon invoking this function the server starts taking further requests from any client

Parameters:
    None
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.stop_tracking_conn_sock(ss)

The evluaserver and evlua platforms ensure that any new connections made during the processing
of a request are kept track of and are closed at the end of request processing.
If this function is called for a connected stream socket, the stream socket is taken off the
list of tracked sockets, so that the connection can be used across multiple requests. Typically
such connections are held in a pool.

Paramters:
    ss: Connected stream socket.
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.track_ss_as_websocket(ss, [msg_handler])

Upgrades a connected stream socket to WEBSCOKET and adds it to the list of sockets tracked by the server
for incoming messages

Parameters:
    ss: Connected stream socket
    msg_handler: optional string, a lua file that implements a websocket message handler.
Return:
    None

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.websocket_active(ss)

Checks if the underlying socket fd of the websocket is active or not

Parameters:
    ss: Handle to websocket (stream socket)
Return:
    status: boolean, true if active, false otherwise

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.compress_data(input_data[, length])

Compresses the input data using zlib compression

Parameters:
    input_data   : string/userdata, the input data to be compressed
    length       : number, required in case input_data is userdata
Return:
    out_data     : userdata, compressed output
    length       : number, length of the compressed output

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.uncompress_text_data(input_data, length)

Deompresses the input data using zlib inflate and returns text (string)

Parameters:
    input_data   : userdata, the input data to be uncompressed
    length       : number
Return:
    out_data     : string, uncompressed output

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall

platform.uncompress_binary_data(input_data, length)

Decompresses the input data using zlib inflate and returns binary (userdata)

Parameters:
    input_data   : userdata, the input data to be uncompressed
    length       : number
Return:
    out_data     : userdata, uncompressed output
    length       : number

ERROR:
    Any error is thrown using perror, can be caught using pcall / xpcall