PHP socket server documentation

Oct 17th, 2013
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. Properties:
  3. running: read-only boolean indicating if the server is running or not
  4. packetLimit: maximum amount of bytes a client can send in a single packet
  5. before overflowing (0 = no limit)
  6. clients: read-only array with all the client IDs. This will fail if
  7. the client is not running
  8. groups: read-only array with all the group IDs. This will fail if
  9. the client is not running
  10. newGroupID: read-only integer having an unused group ID. This will fail
  11. if the client is not running
  12. openCallback: callback to be invoked when a new connection arrives. The
  13. callback receives as arguments the new client's ID and the
  14. server object itself
  15. closeCallback: callback to be invoked when a client closes its connection.
  16. The callback receives as arguments the closed client's old
  17. ID (now become invalid) and the server object itself
  18. receiveCallback: callback to be invoked when a packet arrives from a client.
  19. The callback receives as arguments the received packet (as
  20. a string), the sender client's ID and the server object
  21. overflowCallback: callback to be invoked when a connection overflows the
  22. maximum packet size (as imposed by packetLimit). When this
  23. occurs, any further data received from that client should
  24. not be relied upon (therefore, closing the connection here
  25. is recommended). The callback receives the client's ID and
  26. the server object as arguments.
  27. Any of the first three callback properties can be set to false, in which case
  28. no callback is invoked. If overflowCallback is set to false, a default callback
  29. which closes the connection and invokes closeCallback is used.
  31. splitMode, delimiter: these two properties work together, and specify how the
  32. data received by the client should be split into packets.
  33. Legal values for splitMode (and their semantics, together
  34. with the meanings for delimiter they specify) are these:
  35. Value Semantics
  36. --------------------------------- ---------------------------------------------
  37. SERVER_SPLIT_PACKET No splitting is performed, packets are sent
  38. to the reception callback as received. This
  39. is useful if the implementor wants to handle
  40. the splitting instead of letting the server
  41. do so. The value of delimiter is meaningless.
  42. It should be noted that packetLimit is also
  43. used as the maximum packet size to receive at
  44. once -- if there's no limit, a default of two
  45. kilobytes is used.
  46. --------------------------------- ---------------------------------------------
  47. SERVER_SPLIT_CHAR Packets are split when a certain character is
  48. encountered. The value of delimiter specifies
  49. the character, and it should be either the
  50. value of the character (from 0 to 255) or a
  51. string of length one containing it. The
  52. character in question is discarded and not
  53. sent to the reception callback.
  54. --------------------------------- ---------------------------------------------
  55. SERVER_SPLIT_NEWLINES Packets are split at newline boundaries (that
  56. SERVER_SPLIT_NEWLINES_NO_BLANKS is, at CR, LF or CRLF). The delimiter value
  57. is meaningless. The newline separator is
  58. discarded. The _NO_BLANKS version also makes
  59. lines of length zero to be discarded.
  60. It should be noted that the default split
  62. --------------------------------- ---------------------------------------------
  63. SERVER_SPLIT_LENGTH Packets are split at fixed length boundaries.
  64. The value of delimiter specifies how many
  65. bytes a packet will have, and it should be a
  66. positive integer.
  67. --------------------------------- ---------------------------------------------
  68. SERVER_SPLIT_BYTES_AFTER_BYTE Packets are split at a certain amount of
  69. SERVER_SPLIT_BYTES_AFTER_16LE bytes specified by a value in the packet
  70. SERVER_SPLIT_BYTES_AFTER_16BE itself. The delimiter property indicates how
  71. SERVER_SPLIT_BYTES_AFTER_32LE many bytes offset from the beginning will
  72. SERVER_SPLIT_BYTES_AFTER_32BE this value be, and it should be a positive
  73. integer or zero. The size of the value itself
  74. and its endianness are specified by the value
  75. of splitMode (one of the five constants).
  76. That value indicates how many more bytes
  77. after it will the packet have, at which point
  78. the packet is split.
  79. --------------------------------- ---------------------------------------------
  82. Methods:
  84. open(port):
  85. Opens the server, listening on all available IPs at the specified port. (The
  86. server uses TCP/IPv4 connections.) This method will not return while the
  87. server is running, although it will call the callbacks when needed. This
  88. method returns 0 if the server is closed manually (calling the close() method),
  89. or a negative error constant if something fails:
  90. SERVER_ERROR_INVALID_PORT: the specified port is not a valid port
  91. (ports are positive integers no larger
  92. than 65535)
  93. SERVER_ERROR_CANNOT_CREATE_SOCKET: creating the listening socket failed.
  94. This might happen if the specified port
  95. is busy, or if you don't have the needed
  96. privileges to listen at that port
  97. SERVER_ERROR_CANNOT_READ: an error occurred while attempting to
  98. receive data from active connections
  99. SERVER_ERROR_LISTENING_SOCKET_KILLED: the listening socket that the server
  100. uses to run was closed by an agent
  101. external to the server
  102. SERVER_ERROR_ALREADY_RUNNING: open() was called when the server was
  103. running. Call close() before reopening
  105. close():
  106. Closes the server. This will close all outstanding client connections, flush
  107. all buffers, delete all groups and call no callbacks.
  109. send(client, data, mode = SERVER_SEND_ALL):
  110. <can only be called when the server is running>
  111. Sends the specified data to the specified client. If client is an array, it
  112. sends that data to all clients. Data can be an integer (in which case it is
  113. truncated to 8 bits and sent as a single byte); an array of byte-wide (i.e.,
  114. integers from 0 to 255) values, which are sent as a single buffer; or a string,
  115. which is sent according to the sending mode. The sending mode is one of the
  116. following values:
  117. SERVER_SEND_ALL: the buffer is sent as-is, without any modifications
  118. any positive integer: a buffer as big as the value specifies is sent. If the
  119. string is larger, it is truncated; if it is smaller, it
  120. is padded with nulls
  121. SERVER_SEND_LINE: sends only the first line (up to a CR, LF or CRLF),
  122. including its terminator
  123. SERVER_SEND_LINE_NO_NEWLINE: same as SERVER_SEND_LINE dropping the terminator
  125. SERVER_SEND_LINE_NO_NEWLINE but adding the specified
  126. terminator
  128. broadcast(data, group = 0, mode = SERVER_SEND_ALL):
  129. <can only be called when the server is running>
  130. Sends the specified data to the specified group of recipients. A value of 0
  131. for group indicates all connected clients; a negative value, all clients but
  132. the one specified by the absolute value of that number; and a positive one, all
  133. clients added to a certain group. The value of mode is the same as for send()
  135. disconnect(client):
  136. <can only be called when the server is running>
  137. Disconnects a client. Also causes its buffer to be flushed with no callbacks
  138. being called in the process. If client is an array, all specified clients are
  139. disconnected.
  141. disconnectMultiple(group = 0):
  142. <can only be called when the server is running>
  143. Disconnects a group of clients. The value of group has the same meaning as for
  144. broadcast().
  146. groupsOf(client):
  147. <can only be called when the server is running>
  148. Returns an array with all the groups the specified client is a member of.
  150. joinGroup(client, group):
  151. <can only be called when the server is running>
  152. Makes a client join a group. If the group doesn't exist yet, it is created.
  153. Both arguments can be arrays, in which case the method is called for every
  154. element of the array. (If both are arrays simultaneously, it is called for
  155. every pair.)
  157. leaveGroup(client, group):
  158. <can only be called when the server is running>
  159. Makes a client leave a group. If it's the last client in that group, the group
  160. is deleted. Like for joinGroup(), both arguments can be arrays.
  162. deleteGroup(group):
  163. <can only be called when the server is running>
  164. Deletes a group, making all clients in it leave it. The argument can be an
  165. array, in which case all specified groups are deleted.
  167. clientCallback(client):
  168. <can only be called when the server is running>
  169. clientCallback(client, callback):
  170. Returns or sets a callback for receiving data on a client. Any events that
  171. occur on this client (other than an overflow) cause the client's callback to be
  172. called instead of the normal callback. (Setting it to false reverts to the
  173. default behavior.) The callback receives the packet (null if the event is a
  174. connection close), the server object itself, and the client's ID.
RAW Paste Data Copied