/docs/reference/Networking/Socket/Socket/index.html

https://github.com/richcollins/io · HTML · 526 lines · 520 code · 6 blank · 0 comment · 0 complexity · 1a995a1788ddaa81a13f709afaeaf9b2 MD5 · raw file

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  2. <html>
  3. <head>
  4. <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
  5. <title>Socket</title>
  6. <META HTTP-EQUIV="EXPIRES" CONTENT=0>
  7. <link rel="stylesheet" href="../../../../docs.css">
  8. </head>
  9. <body>
  10. <br>
  11. <h1>Io Reference</h1>
  12. <br><br><br>
  13. <br><br><br>
  14. <a class='column' href='../../index.html'>Networking</a>
  15. &nbsp;&nbsp;<font color=#ccc>/</font>&nbsp;&nbsp;
  16. <a class='column' href='../index.html'>Socket</a>
  17. &nbsp;&nbsp;<font color=#ccc>/</font>&nbsp;&nbsp;
  18. <b>Socket</b>
  19. <br><br><br>
  20. <br><br><br>
  21. <table border=0 cellspacing=0 style="margin-left:8em; width:40em; line-height:1.2em;">
  22. <tr>
  23. <td align=right></td>
  24. <td></td>
  25. <td>Interface to network communication.
  26. Sockets will auto yield to other coroutines while waiting on a request.
  27. All blocking operations use the timeout settings of the socket.
  28. Reads are appended to the socket's read buffer which can
  29. be accessed using the readBuffer method.
  30. Example:
  31. <pre>
  32. socket := Socket clone setHost("www.yahoo.com") setPort(80) connect
  33. if(socket error) then( write(socket error, "\n"); exit)
  34. socket write("GET /\n\n")
  35. while(socket read, Nop)
  36. if(socket error) then(write(socket error, "\n"); exit)
  37. write("read ", socket readBuffer length, " bytes\n")
  38. </pre>
  39. </td></tr>
  40. <tr><td colspan=3>&nbsp;</td></tr>
  41. <tr><td colspan=3>&nbsp;</td></tr>
  42. <tr><td colspan=3>&nbsp;</td></tr>
  43. <tr>
  44. <td align=right>
  45. </td>
  46. <td></td>
  47. <td>
  48. <hr align=left color=#ddd height=1>
  49. <br><br>
  50. <a name="Socket-acceptTimeout"></a><b>
  51. acceptTimeout
  52. </b>
  53. <p>
  54. <div class=slotDescription>
  55. Returns the length of time in seconds for accept timeouts on the socket.
  56. </div>
  57. <a name="Socket-appendToWriteBuffer"></a><b>
  58. appendToWriteBuffer(aSequence)
  59. </b>
  60. <p>
  61. <div class=slotDescription>
  62. Appends aSequence to the write buffer if it is non-nil. Returns self.
  63. </div>
  64. <a name="Socket-asyncAccept"></a><b>
  65. asyncAccept(ipAddressObject)
  66. </b>
  67. <p>
  68. <div class=slotDescription>
  69. Immediately returns a socket for a connection if one is available or nil otherwise. Returns an Error object on error.
  70. </div>
  71. <a name="Socket-asyncBind"></a><b>
  72. asyncBind
  73. </b>
  74. <p>
  75. <div class=slotDescription>
  76. Binds the socket and returns self immediately or an Error object on error.
  77. </div>
  78. <a name="Socket-asyncConnect"></a><b>
  79. asyncConnect(ipAddressObject)
  80. </b>
  81. <p>
  82. <div class=slotDescription>
  83. Connects to the given IPAddress and returns self or an Error object on error.
  84. </div>
  85. <a name="Socket-asyncListen"></a><b>
  86. asyncListen
  87. </b>
  88. <p>
  89. <div class=slotDescription>
  90. Listens to the socket and returns self immediately or an Error object on error.
  91. </div>
  92. <a name="Socket-asyncStreamOpen"></a><b>
  93. asyncStreamOpen
  94. </b>
  95. <p>
  96. <div class=slotDescription>
  97. Submits an async request to open the socket in stream mode and returns self immediately or an Error object on error.
  98. </div>
  99. <a name="Socket-asyncStreamRead"></a><b>
  100. asyncStreamRead(aSeq, readSize)
  101. </b>
  102. <p>
  103. <div class=slotDescription>
  104. Reads up to readSize number of bytes into aSeq if data is available.
  105. Returns self immediately if successful. Returns an error object on Error. Returns nil if the socket is disconnected.
  106. </div>
  107. <a name="Socket-asyncStreamWrite"></a><b>
  108. asyncStreamWrite(aSeq, start, writeSize)
  109. </b>
  110. <p>
  111. <div class=slotDescription>
  112. Writes the slice of aSeq from start to start + writeSize to the socket.
  113. Returns self immediately if successful, otherwise closes the socket.
  114. Returns an error object on Error.
  115. Returns nil if the socket is disconnected.
  116. </div>
  117. <a name="Socket-asyncUdpOpen"></a><b>
  118. asyncUdpOpen
  119. </b>
  120. <p>
  121. <div class=slotDescription>
  122. Submits an async request to open the socket in UDP mode and returns self immediately or an Error object on error.
  123. </div>
  124. <a name="Socket-asyncUdpRead"></a><b>
  125. asyncUdpRead(ipAddress, aSeq, readSize)
  126. </b>
  127. <p>
  128. <div class=slotDescription>
  129. Reads up to readSize number of bytes from ipAddress into aSeq if data is available.
  130. Returns self immediately if successful. Returns an error object on Error. Returns nil if the socket is disconnected.
  131. </div>
  132. <a name="Socket-asyncUdpWrite"></a><b>
  133. asyncUdpWrite(ipAddress, aSeq, startIndex, readSize)
  134. </b>
  135. <p>
  136. <div class=slotDescription>
  137. Writes readsize bytes from aSeq starting at startIndex to ipAddress.
  138. Returns self immediately if successful. Returns an error object on Error. Returns nil if the socket is disconnected.
  139. </div>
  140. <a name="Socket-bytesPerRead"></a><b>
  141. bytesPerRead
  142. </b>
  143. <p>
  144. <div class=slotDescription>
  145. Returns number of bytes to read per read call.
  146. </div>
  147. <a name="Socket-bytesPerWrite"></a><b>
  148. bytesPerWrite
  149. </b>
  150. <p>
  151. <div class=slotDescription>
  152. Returns number of bytes to write per write call.
  153. </div>
  154. <a name="Socket-close"></a><b>
  155. close
  156. </b>
  157. <p>
  158. <div class=slotDescription>
  159. Closes the socket and returns self. Returns nil on error.
  160. </div>
  161. <a name="Socket-connect"></a><b>
  162. connect
  163. </b>
  164. <p>
  165. <div class=slotDescription>
  166. Connects to the socket's host. Returns self on success or an Error object on error.
  167. </div>
  168. <a name="Socket-connectTimeout"></a><b>
  169. connectTimeout
  170. </b>
  171. <p>
  172. <div class=slotDescription>
  173. Returns the length of time in seconds for connect timeouts on the socket.
  174. </div>
  175. <a name="Socket-descriptorId"></a><b>
  176. descriptorId
  177. </b>
  178. <p>
  179. <div class=slotDescription>
  180. Returns the socket's file descriptor id as a Number.
  181. </div>
  182. <a name="Socket-errorDescription"></a><b>
  183. errorDescription
  184. </b>
  185. <p>
  186. <div class=slotDescription>
  187. Returns a description of the last error on the socket as a string.
  188. </div>
  189. <a name="Socket-errorNumber"></a><b>
  190. errorNumber
  191. </b>
  192. <p>
  193. <div class=slotDescription>
  194. Returns the socket error number for the last error.
  195. </div>
  196. <a name="Socket-getSocketReadLowWaterMark"></a><b>
  197. getSocketReadLowWaterMark
  198. </b>
  199. <p>
  200. <div class=slotDescription>
  201. Returns the read low water mark for the socket on success or nil on error.
  202. </div>
  203. <a name="Socket-getSocketWriteLowWaterMark"></a><b>
  204. getSocketWriteLowWaterMark
  205. </b>
  206. <p>
  207. <div class=slotDescription>
  208. Returns the write low water mark for the socket on success or nil on error.
  209. </div>
  210. <a name="Socket-host"></a><b>
  211. host
  212. </b>
  213. <p>
  214. <div class=slotDescription>
  215. Returns the host for the socket.
  216. </div>
  217. <a name="Socket-ipAddress"></a><b>
  218. ipAddress
  219. </b>
  220. <p>
  221. <div class=slotDescription>
  222. Returns the IpAddress object for the socket.
  223. </div>
  224. <a name="Socket-isOpen"></a><b>
  225. isOpen
  226. </b>
  227. <p>
  228. <div class=slotDescription>
  229. Returns true if the socket is open, false otherwise.
  230. </div>
  231. <a name="Socket-isStream"></a><b>
  232. isStream
  233. </b>
  234. <p>
  235. <div class=slotDescription>
  236. Returns true if the socket is a stream, false otherwise.
  237. </div>
  238. <a name="Socket-isValid"></a><b>
  239. isValid
  240. </b>
  241. <p>
  242. <div class=slotDescription>
  243. Returns true if the socket is in valid state, closes the socket and returns false otherwise.
  244. </div>
  245. <a name="Socket-port"></a><b>
  246. port
  247. </b>
  248. <p>
  249. <div class=slotDescription>
  250. Returns the port number for the socket.
  251. </div>
  252. <a name="Socket-readBytes"></a><b>
  253. readBytes(numBytes)
  254. </b>
  255. <p>
  256. <div class=slotDescription>
  257. Reads the socket until its readBuffer is numBytes long, then returns a Sequence
  258. containing the first numBytes of readBuffer's contents and clips that section from the readBuffer.
  259. </div>
  260. <a name="Socket-readListMessage"></a><b>
  261. readListMessage
  262. </b>
  263. <p>
  264. <div class=slotDescription>
  265. A shortcut for List fromEncodedList(socket readMessage).
  266. </div>
  267. <a name="Socket-readMessage"></a><b>
  268. readMessage
  269. </b>
  270. <p>
  271. <div class=slotDescription>
  272. Empties the readBuffer and reads a 4 byte uint32 in network byte order.
  273. This number is the number of bytes in the message payload which are
  274. then read into the socket's readBuffer. The readBuffer is returned.
  275. </div>
  276. <a name="Socket-readTimeout"></a><b>
  277. readTimeout
  278. </b>
  279. <p>
  280. <div class=slotDescription>
  281. Returns the length of time in seconds for read timeouts on the socket.
  282. </div>
  283. <a name="Socket-readUntilSeq"></a><b>
  284. readUntilSeq(aSequence)
  285. </b>
  286. <p>
  287. <div class=slotDescription>
  288. Reads the socket until its readBuffer contains aSequence, then returns a Sequence
  289. containing the readBuffer's contents up to (but not including) aSequence and clips that section from the readBuffer.
  290. </div>
  291. <a name="Socket-serverOpen"></a><b>
  292. serverOpen
  293. </b>
  294. <p>
  295. <div class=slotDescription>
  296. Opens the socket as a stream, binds it to its ipAddress and calls asyncListen to prepare the socket to accept connections.
  297. Returns self on success or an Error object on error.
  298. </div>
  299. <a name="Socket-serverWaitForConnection"></a><b>
  300. serverWaitForConnection
  301. </b>
  302. <p>
  303. <div class=slotDescription>
  304. Waits for a connection or timeout. When a connection is received, this method returns the connection socket.
  305. An Error object is returned on timeour or error.
  306. </div>
  307. <a name="Socket-setAcceptTimeout"></a><b>
  308. setAcceptTimeout(seconds)
  309. </b>
  310. <p>
  311. <div class=slotDescription>
  312. Sets the length of time in seconds for accept timeouts on the socket. Returns self.
  313. </div>
  314. <a name="Socket-setBytesPerRead"></a><b>
  315. setBytesPerRead(numberOfBytes)
  316. </b>
  317. <p>
  318. <div class=slotDescription>
  319. Sets number of bytes to read per read call. Returns self.
  320. </div>
  321. <a name="Socket-setBytesPerWrite"></a><b>
  322. setBytesPerWrite(numberOfBytes)
  323. </b>
  324. <p>
  325. <div class=slotDescription>
  326. Sets number of bytes to write per write call. Returns self.
  327. </div>
  328. <a name="Socket-setConnectTimeout"></a><b>
  329. setConnectTimeout(seconds)
  330. </b>
  331. <p>
  332. <div class=slotDescription>
  333. Sets the length of time in seconds for connect timeouts on the socket. Returns self.
  334. </div>
  335. <a name="Socket-setHost"></a><b>
  336. setHost(hostName)
  337. </b>
  338. <p>
  339. <div class=slotDescription>
  340. Translates hostName to an IP using asynchronous DNS and sets
  341. the host attribute. Returns self.
  342. </div>
  343. <a name="Socket-setHost"></a><b>
  344. setHost(hostNameOrIpString)
  345. </b>
  346. <p>
  347. <div class=slotDescription>
  348. Set the host for the socket. Returns self on success, an Error object otherwise.
  349. </div>
  350. <a name="Socket-setIpAddress"></a><b>
  351. setIpAddress(ipAddressObject)
  352. </b>
  353. <p>
  354. <div class=slotDescription>
  355. Sets the ipAddress for the socket. Returns self. The setHost() method should generally be used to set the host instead of this method.
  356. </div>
  357. <a name="Socket-setNoDelay"></a><b>
  358. setNoDelay
  359. </b>
  360. <p>
  361. <div class=slotDescription>
  362. Sets the socket to be no-delay. Returns self on success or nil on error.
  363. </div>
  364. <a name="Socket-setPort"></a><b>
  365. setPort(portNumber)
  366. </b>
  367. <p>
  368. <div class=slotDescription>
  369. Sets the port number for the socket, returns self.
  370. </div>
  371. <a name="Socket-setReadTimeout"></a><b>
  372. setReadTimeout(seconds)
  373. </b>
  374. <p>
  375. <div class=slotDescription>
  376. Sets the length of time in seconds for read timeouts on the socket. Returns self.
  377. </div>
  378. <a name="Socket-setSocketReadBufferSize"></a><b>
  379. setSocketReadBufferSize(numberOfBytes)
  380. </b>
  381. <p>
  382. <div class=slotDescription>
  383. Sets the read buffer size for the socket. Returns self on success or nil on error.
  384. </div>
  385. <a name="Socket-setSocketReadLowWaterMark"></a><b>
  386. setSocketReadLowWaterMark(numberOfBytes)
  387. </b>
  388. <p>
  389. <div class=slotDescription>
  390. Sets the read low water mark for the socket. Returns self on success or nil on error.
  391. </div>
  392. <a name="Socket-setSocketWriteBufferSize"></a><b>
  393. setSocketWriteBufferSize(numberOfBytes)
  394. </b>
  395. <p>
  396. <div class=slotDescription>
  397. Sets the write buffer size for the socket. Returns self on success or nil on error.
  398. </div>
  399. <a name="Socket-setSocketWriteLowWaterMark"></a><b>
  400. setSocketWriteLowWaterMark(numberOfBytes)
  401. </b>
  402. <p>
  403. <div class=slotDescription>
  404. Sets the write low water mark for the socket. Returns self on success or nil on error.
  405. </div>
  406. <a name="Socket-setWriteTimeout"></a><b>
  407. setWriteTimeout(seconds)
  408. </b>
  409. <p>
  410. <div class=slotDescription>
  411. Sets the length of time in seconds for write timeouts on the socket. Returns self.
  412. </div>
  413. <a name="Socket-streamOpen"></a><b>
  414. streamOpen
  415. </b>
  416. <p>
  417. <div class=slotDescription>
  418. Opens the socket in stream mode. Returns self.
  419. </div>
  420. <a name="Socket-streamRead"></a><b>
  421. streamRead(numberOfBytes)
  422. </b>
  423. <p>
  424. <div class=slotDescription>
  425. Reads numberOfBytes from the socket into the socket's readBuffer.
  426. Returns self when all bytes are read or an Error object on error.
  427. </div>
  428. <a name="Socket-streamReadNextChunk"></a><b>
  429. streamReadNextChunk(optionalProgressBlock)
  430. </b>
  431. <p>
  432. <div class=slotDescription>
  433. Waits for incoming data on the socket and when found, reads any available data and returns self.
  434. Returns self on success or an Error object on error or timeout.
  435. </div>
  436. <a name="Socket-streamReadWhileOpen"></a><b>
  437. streamReadWhileOpen
  438. </b>
  439. <p>
  440. <div class=slotDescription>
  441. Reads the stream into the socket's readBuffer until it closes.
  442. Returns self on success or an Error object on error.
  443. </div>
  444. <a name="Socket-streamWrite"></a><b>
  445. streamWrite(buffer, optionalProgressBlock)
  446. </b>
  447. <p>
  448. <div class=slotDescription>
  449. Writes buffer to the socket.
  450. If optionalProgressBlock is supplied, it is periodically called with the number of bytes written as an argument.
  451. Returns self on success or an Error object on error.
  452. </div>
  453. <a name="Socket-udpOpen"></a><b>
  454. udpOpen
  455. </b>
  456. <p>
  457. <div class=slotDescription>
  458. Opens the socket in UDP (connectionless) mode. Returns self.
  459. </div>
  460. <a name="Socket-udpRead"></a><b>
  461. udpRead(ipAddress, numBytes)
  462. </b>
  463. <p>
  464. <div class=slotDescription>
  465. Waits for and reads numBytes of udp data from the specified ipAddress into the socket's readBuffer.
  466. Returns self on success or an Error object on error.
  467. </div>
  468. <a name="Socket-udpReadNextChunk"></a><b>
  469. udpReadNextChunk(ipAddress)
  470. </b>
  471. <p>
  472. <div class=slotDescription>
  473. Waits to receive UDP data from the specified ipAddress.
  474. As soon as any data is available, it reads all of it into the socket's readBuffer.
  475. Returns self on success or an Error object on error.
  476. </div>
  477. <a name="Socket-udpWrite"></a><b>
  478. udpWrite
  479. </b>
  480. <p>
  481. <div class=slotDescription>
  482. Same as asyncUdpWrite.
  483. </div>
  484. <a name="Socket-writeFromBuffer"></a><b>
  485. writeFromBuffer(optionalProgressBlock)
  486. </b>
  487. <p>
  488. <div class=slotDescription>
  489. Writes the contents of the socket's writeBuffer to the socket.
  490. If optionalProgressBlock is supplied, it is periodically called with the number of bytes written as an argument.
  491. Returns self on success or an Error object on error.
  492. </div>
  493. <a name="Socket-writeListMessage"></a><b>
  494. writeListMessage(aList)
  495. </b>
  496. <p>
  497. <div class=slotDescription>
  498. A shortcut for writeMessage(aList asEncodedList).
  499. </div>
  500. <a name="Socket-writeMessage"></a><b>
  501. writeMessage(aSeq)
  502. </b>
  503. <p>
  504. <div class=slotDescription>
  505. Writes a 4 byte uint32 in network byte order containing the size of aSeq.
  506. Then writes the bytes in aSeq and returns self.
  507. </div>
  508. <a name="Socket-writeTimeout"></a><b>
  509. writeTimeout
  510. </b>
  511. <p>
  512. <div class=slotDescription>
  513. Returns the length of time in seconds for write timeouts on the socket.
  514. </div>
  515. </td>
  516. </tr>
  517. </table>
  518. <br><br><br><br><br>
  519. </body>
  520. </html>