SEVER

Classes

• vorlib::server
• vorlib::socket_e (exception)
• vorlib::server_socket (virtual, internal use only)
• vorlib::address

Types

• vorlib::server_socket_type

  This type is enum specifying type of socket used in server. See below. Values are:
  • sst_none - this shouldn't be in the server, it's just for internal controls. If you find one there, you found a bug.
  • sst_tcp_listen - this socket listens for incoming tcp connection and can not send or receive data.
  • sst_tcp_waiting_connect - this will be tcp socket, however, it needs some time to connect to remote host. While waiting, it's this.
  • sst_tcp_transfer - connected tcp socket, where you can put data to send or read data, when they arrive.
  • sst_line_transfer - it is as well tcp connected socket, however, incoming data are buffered and you get them by lines. Makes easier parsing text based protocols.
  • sst_console - this is not a socket, strictly talking. If you want to wait for data from network as well as read standart console, you can use this. Then, an event is called whenever some data are ready on console. Note that this does NOT work on windows. You may not get just one char a time, if your system uses buffered console.
  • sst_line_console - it is very similar to that above, however, here you are sure that you will get data by one line a time, no matter what console you r system use. This also does not work under windows.

• vorlib::delsocket_reason

  This enum is used in event telling user (by user I mean someone who uses this class in his code), why a socket has been closed. Values are here:
  • dsr_local_closed - you closed the socket.
  • dsr_remote_closed - the remote host closed it. The local endpoind is closed automatically.
  • dsr_error - socket can not live any more due to a fatal error.

• vorlib::address_family

  This specifies, witch addresses you want to use with a socket. Values are:
  • af_ipv4: standart ip address.
  • af_ipv6: that new version of ip with 16 bytes long address.

• vorlib::long_sockaddr

  It is replacement for the system sockaddr, witch is too small for ipv6. You can easily ignore this one.

• vorlib::ipv4_addr & vorlib::ipv6_addr

  Theese two are used for easier manipulation with long_sockaddr. They are used internally and you may just ignore them.

Files

• socket.h
• socket.cpp

The address class is for giving address to a socket.

Interface of address

• address

  Constructor, creates the address. It may have this faces:
  • address(); - not recomended, the address will contain unspecified address. Do not use this.
  • address(const std::string &address, int port); - the ip address is looked up automatically and decided, weather the ipv4 or ipv6 will be used
  • address(char _1, char _2, char _3, char _4, int port); - define ipv4 addres in format _1._2._3._4
  • address(unsigned addr, int port); - define ipv4 address int network byte order format.
  • address(const long_sockaddr *addr, int length); - give it already prepared address, like for system functions. The length is optional.

• get_af

  Returns actually used address family (ipv4 or ipv6 at the moment).

• get_port

  Returns port number.

• get_addr

  Returns pointer to long_sockaddr, it can be used directly for system functions. This is more for internal use, however, you may need it.

• get_str_addr

  Puts address into human-readable format and returns it as std::string.

• get_un_address

  Returns address as unsigned. This works only for ipv4 addresses and is not recomended to use.

Interface of server

• server

  It is constructor, called automatically.

• ~server

  Destructor, called automatically.

• operator=

  This is here to be sure nobody will be able to copy the server. Do not call it and do not copy the server.

• tcp_listen

  This will create a socket witch will listen for incoming connection. Parameters are: address, maxqueue. Address is vorlib::address class, specifying, how to listen and maxqueue is max number of waiting connections. Maxqueue is optional. You may replace the address only by port number. If you don't set the address, all connections will be allowed. If you get a connection, you can accept it or reject. If you accept it, you can select, wether it will be line socket or tcp socket.

• tcp_connect

  This will create a socket witch will try to connect to given address. It is probable that this will take some time, so it will tell you, when it is done (or when it fails). In the meantime, the waiting socket will be sst_tcp_waiting_connect. As a parameter it takes address class, specifying, where to connect.

• line_connect

  This acts like tcp_connect, however, after connecting, it will be sst_line_transfer instead of sst_tcp_transfer (and the incoming data will be buffered by lines).

• add_udp_socket

  This server will be able to manage udp sockets as well. This will create new udp socket. However, udp sockets are not implemented yet. An optional parameter is address family - ipv4 or 6.

• set_udp_local

  Sets socket's (firts parameter its identificator) local port (second parameter). It is good idea to set it, if you want to act as a server, so you will know, on witch port it is on.

• set_udp_destination

  Sets destination address (second parameter, vorlib::address) of given socket (first parameter, identificator=int). Any future data will be sent there, however, if there are any data waiting in the queue, they will be sent to the old address and port. You have to set the destination before you send any data trough this socket, or you get an exception (23, imposible request)

• get_udp_source

  Returns source address (as vorlib::address) of last incoming packet for socket identified by the first parameter. If there were no data from the begining of socket's life, you'll gwt an exception (29, address not ready)

• add_console

  This will start scaning console as well, and when there is some input on it, it will notify you. However, console can be scanned only once (eather in add_console or add_line_console).

• add_line_console

  This will scan console and notify you, whenever there is a line. You can not scan console by add_console and add_line_console in the same time. Note, that the console is read automatically, so if you try to read it while the server is running, there will be no input. You will get the input trough the event (onconsoleline).

• close_socket

  Tell the socket to close its connection and get away. As a parameter, the function takes int as a socket identificator. You will get this whenever a new socket is created and you can scan all sockets as well.

• go

  This will start the server. This function won't finish, until you call terminate. When you call this, the server will manage all sockets and will provide you events. As an optional parameter, you can give it refresh rate, in seconds. This is used for server timer and to be sure it will not hang forever, if there is some system bug. Any data arriving and similar things will be noticed imediatelly, no matter what you set here. Do not set to 0, it would take whole CPU time. You should set it to shorter time than is a server-timer interval, or, if you don't use it, to some reasonable value, lets say 60.

• terminate

  This will tell the server to stop running, if you call it from inside an event. If the server is not running, it will have no effect.

• set_onerror

  You can set an error handling event. As a parameter provide function with prototype: void [name of the function](vorlib::socket_e *error, vorlib::server *caller). Error is the error that just happened and caller can be used to distinguish the server, if you have more instances. You shouldn't let any exception get outside, it is recommended to place whatever you are doing between try{ } catch(...).

  You can terminate() the server from here.

  If you do not set this event and there is an exception, the server will terminate imediatelly, so it is recomended to provide one.

• get_onerror

  This one will return previously set onerror function or NULL if you did not set it.

• set_onnewsocket

  This event is called whenever a new socket is born, no matter why (you created it, incoming connection). The handling function has this prototype: void [function name](int socket, server_socket_type type, vorlib::server *caller). The socket is identificator of the new socket. The type is type of the socket and the caller is the calling server. It can help you remember, what socket you have.

• get_onnewsocket

  Returns the onnewsocket handling function you set, or NULL if you did not set that.

• set_ondelsocket

  This event is just the oposite of the onnewsocket. It is called every time a socket is closed. The prototype is void [name of the handler](int socket, server_socket_type type, delsocket_reason reason, vorlib::server *caller). The socket is an id of the dying socket, type is type of that socket, reason is reason, why it was deleted and caller is the calling server.

• get_ondelsocket

  Returns the actual ondelsocket function, or NULL if none set.

• set_ontimer

  Set this handler, if you want to do something time-to-time. It is called in set interval and you can check, for examle, weather some peers are responding in time limit. Prototype: void [name of func](vorlib::server *caller). The caller is the sarver causing this call.

• get_ontimer

  Returns actually set handler of the ontimer event.

• set_interval

  You can set interval in witch the ontimer event will be called. It is in seconds. Note, that it is not exact at all, depends on the system load and refresh interval.

• get_interval

  Returns actual interval for timer.

• set_onconsoleready

  This event is called if you scan console by add_console and there are some data waiting. The prototype is this: void [name of your function](vorlib::server *caller). The caller is the server now calling. You have to read it manually.

• get_onconsoleready

  Returns value of the onconsoleready event.

• set_onconsoleline

  This event is called when you scan the console by "add_line_console" and there is a line ready. The prototype is this: void [name of the func] (const std::string &line, vorlib::server* caller). The line contains the line text and the caller is the server that caused the event.

• get_onconsoleline

  Returns value of the onconsoleline event.

• set_ondataarrive

  The dataarriveevent is the event, that is called when some data are ready. If you use, for example, sst_tcp_transfer, you will get it imediatelly, if you use something like sst_line_ttransfer socket, you will get them by whole lines, whenever they are ready, together with some newlines and such characters at the end. The prototype is this: void [name of the function](int socket, const char *buffer, int size, vorlib::server *caller). The socket is socket id, so you know, where it comes from. The buffer contains the date, if it is the tcp_line_socket (or something similar in future), it can be casted do const char *, because the data contains the trailing NUL character, but note, that it contains the newline at the end. The size indicates, how many of data arrived (without the NUL character, so it is the same that would be returned by strlen) and caller is the originating server.

• get_ondataarrive

  It will return the function assigned to indataarrive event.

• set_ontcplisten

  In the ontcplisten function, you can handle incoming connections. Whenever you listen with a tcp socket and some new connection arrives, you are asked, what to do with it in this function. The prototype is this: vorlib::server_socket_type [name of your function] (vorlib::address addr, int orig_sock, int new_sock, vorlib::server *caller). The addr is host format ip address, the port is host format port number, the orig_sock is the listening socket identificator, the new_sock is identificator of the new incoming connection, so it can be added to your list in this event (note, that the onnewsocket will be called for it as well). You can return sst_none, if you want to reject the connection (it will be closed imediatelly), sst_tcp_transfer, if you want it to become a tcp socket or sst_line_transfer to create a line socket.

• get_ontcplisten

  Returns value of the ontcplisten event.

• set_onqueueempty

  The onqueueempty event is called, whenever some socket's queue for outgoing data becomes empty. It means it will be called if you send soma data and they are send out (all of them), but it will be called only once before you send another data. The other time it is called is when a socket is actually connected to remote endpoint and you did not fill the queue before. The prototype of the handler is: void [the name] (int socket, vorlib::server *caller). The socket is identificator of the socket witch queue became empty and the caller is the server containing it.

• get_onqueueempty

  Returns the onqueue event handler.

• set_ondatasent

  This event is called whenever some data from queue are sent (that means that any data going out will cause this). If the queue becomes empty with this send, the onqueueempty event is called as well. Protytope is this: void [name] (int socket, int queuesize, vorlib::server *caller). The socket is socket identificator, witch data were sent, queuesize means, how many data are left in the queue and caller is the server containing this socket.

• get_ondatasent

  Returns ondatasent event.

• get_type

  You can ask of what type is the socket. Pass it the socket identificator and the result will be server_socket_type indicating, of witch type is the socket.

• get_remote_addr

  You can ask the server for the remote endpoint address of given socket (specified by the identificator). You will get unsignet in host format containing the whole address. Note, that some sockets does not have remote endpoint, therefore this will cause an exception. In the case of udp socket, this is the address where are all new packets sent actually.

• get_remote_port

  Returns remote endpoint port number. Some sockets does not have remote endpoint.

• get_sock_count

  Returns number of socket actually existing within the server.

• getsocket & operator[]

  Returns socket identificator on that index. Note, that the socket indexes change trough the time, so it can be used when you want to scan all sockets, but is useless to remeber a socket index and every time you want to do something with it, ask for the identificator.

• get_queueempty

  Ask the socket (specified by identificator), wethaer its queue is empty (returns true) or there are some data waiting to be sent (returns false).

• get_queuesize

  Returns, how many bytes waits to be sent by the socket (specified by the socket identificator). If the queue is empty, it returns 0.

• write_data

  Put some data into queue, so they will be sent out. The first parameter is int, socket identificator. It can continue by size and pointer to data (int and any pointer), or by format c NUL terminated string and values (like in printf). However, this works only up to 10 kB string after combining the walues together. The NUL char is not sent.

• add_data

  This void * variable can be any data you may want to bind the server with. Just put there enything. But note, that it is not freed with the server, you create it and you have to free it as well.

Functions

• getaddr

  This function can be used to give an address as a parameter, if you don't want to create it manually and care about freeing. Just call some_function(addr(parameters)); The getaddr function may look like this:
  • getaddr(const std::string &address, int port). address is the address of host and port is the port number. It can be eather ipv4 or ipv6 (well, it writes to me, that the network is unreachable, but it does everywhere else as well, so I thing it is not a bug here) address or a host name.
  • getaddr(unsigned addr, int port). This creates an ipv4 address from the address (the four parts between dots are put together inside the address).
  • getaddr(char _1, char _2, char _3, char _4, int port). This creates an ipv4 address as well, but the parts between dots are separated (it would look like _1._2._3._4).
  • getaddr(const long_sockaddr *addr, int length). This is more for internal use, but you can use it as well. You can give it the address directly, in the struct, like it is given to system functions.

Error handling

• -1: Fixme errors, throwed by internal checks. If this happens, it is my fault, not yours. Please, submit a bug
• 4: Couldn't convert host name to ip address. This is caused by wrongly written name, non-working connection or anything similar.
• 5: Could not bind the socket. Binding is done before starting to listen by a socket and it assignes port to the socket. This usually means, that you want a port, that is already used.
• 8: Send error. Data could not be sent, the reason should be still in the errno.
• 10: Receive error. Data could not be read from the socket. The reason is in the errno.
• 14: Error while accepting connection. The reason is inside the errno.
• 16: Remote endpoint does not listen.
• 17: Trying to cope server. Pass it as a reference, but copying makes no sence
• 18: Error while connecting. The reasin for this should be in the errno.
• 19: Select error. Something happened while it tried to wait for some socket to happen something. Consider terminating the server, it may happen every time, so it wouldn't do enything else.
• 20: Trying to scan console twice. You can scan console only once
• 21: Error readingfrom console.
• 22: Identificator is not this server's socket.
• 23: Imposible request. (For example, you try to send data trough listening socket). The description is in the message
• 24: Connection reset by peer. This is often done by windows sockets before closing. It should not be considered as an error in that case.
• 25: Error reading status from socket. You want some info from socket, that does not support it. (For example you want a remote port from console scanning socket). Description is inside the message.
• 26: Error while trying to connect to remote host. The socket that tried to connect will be deleted (because it is useless without the connection).
• 27: Not a udp socket. You requested some operation, witch needs to be done with a udp socket, like set_udp_local, on non-udp socket.
• 28: Unknown address family. This may happen if you create address by giving it long_sockaddr, and you use other than supported address family.
• 29: Address not ready yet. This happens, when you request a source address from an udp socket, when the socket did not yet get any data