# nopoll_conn_new

Definition: | include nopoll.e atom conn = nopoll_conn_new(atom ctx, nullable_string host_ip, host_port, host_name, get_url, protocols, origin)
Description: | Creates a new Websocket connection to the specified destination, as located at host_ip and host_port (IPv4 version). ctx: The noPoll context to which this new connection will be associated, as created by nopoll_ctx_new(). host_ip: The websocket server address to connect to. host_port: The websocket server port to connect to. If NULL is provided, port 80 is used. host_name: The Host: header value that will be sent, used by the websocket server to activate the right virtual host configuration. If null uses host_ip value. get_url: As part of the websocket handshake, an url is passed to the remote server inside a GET method. This parameter allows to configure this. If NULL then / will be used. origin: Websocket origin to be notified to the server. protocols: Optional protocols requested to be activated for this connection (a string or list of strings separated by a white space). If the server accepts the connection you can use nopoll_conn_get_accepted_protocol() to get the protocol accepted by the server. Returns: A reference to the connection created or NULL if it fails. Keep in mind the connection reported may not be connected at the time is returned by this function. You can use nopoll_conn_is_ready() and nopoll_conn_is_ok() to ensure it can be used. There is also a helper function (NOTE it is blocking) that can help you implement a very simple wait until ready operation: nopoll_conn_wait_until_connection_ready() however it is not recommended for any serious, non-command line programming.
Notes: | 1: Is nopoll_conn_new() blocking? Partially. It is blocking with a timeout but just for sending the client init (the initial packet that a WebSocket client must send), but the function does not block the caller until a reply from the server is received and the handshake is completed (which is where the blocking it is likely to happen). So, it essence, nopoll_conn_new (and all its variants) is not blocking (unless you have a problem with network connection causing send() API to fail to send the WebSocket init message by returning EWOULD_BLOCK, which is very likely to not happen), Because of that, the connection returned by this function have big chances to be not ready (that is why you have to use nopoll_conn_is_ready() or the blocking one nopoll_conn_wait_until_connection_ready() to ensure you successfully connected), 2: Control connect timeout To control timeout for sending the initial message (and to ensure the engine sends it), you can use the following functions: nopoll_conn_connect_timeout() nopoll_conn_get_connect_timeout()
Example: | Copy
    include nopoll.e

    atom ctx = nopoll_ctx_new()
    atom conn = nopoll_conn_new(ctx, "echo.websocket.org", "80", NULL, "/", NULL, NULL)

    ...