diff options
Diffstat (limited to 'frontends/riscos/distribution/3rdParty/SocketWatch/Source/!ReadMe')
| -rw-r--r-- | frontends/riscos/distribution/3rdParty/SocketWatch/Source/!ReadMe | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/frontends/riscos/distribution/3rdParty/SocketWatch/Source/!ReadMe b/frontends/riscos/distribution/3rdParty/SocketWatch/Source/!ReadMe deleted file mode 100644 index ea24c7802..000000000 --- a/frontends/riscos/distribution/3rdParty/SocketWatch/Source/!ReadMe +++ /dev/null @@ -1,133 +0,0 @@ -Document v0.07. (C) Dickon Hood, see licence for details of copying etc. - - -SocketWatch -=========== - -SocketWatch is a simple module designed to reduce the requirement of Wimp -applications using sockets to constantly poll them using Null Wimp polls for -data. - -If you're not a programmer, stop reading now, this will probably make little -sense to you. If you are a programmer, but don't write networking -applications, again, this is unlikely to be of interest. - - -Rationale ---------- - -At boot time, my machine loads and runs five seperate applications which -require open sockets. As none of these have support modules associated with -them, I'm assuming that they are constantly polling the sockets they open on -null polls. This is inefficient. - -Sockets can be marked as asynchronous. If they are, an Internet event (19) -is generated whenever something interesting happens to them. Events are only -accessable to modules, however, and are useless in a Wimp environment. The -answer is to write a module which does that and notifies the parent -application that something has happened. If every application did this, -there'd be another five or six modules running on my machine, all doing much -the same job, which I don't need. - -This attempts to address the issue by implementing a module with an open -interface, and one which is generic enough to be applicable to almost every -app. which could want to use it. - - -Usage ------ - -SocketWatch relies upon a feature of Risc OS 3.1 and upwards, so won't work -on ROS2. Sorry, but there we go. - -Sockets are registered with the module. At this point, the socket is marked -as asynchronous (so the parent app. doesn't need to). A pollword and bit -number to set are also supplied. - -As some internal structure has to be created, a pollword of 0 is acceptable, -and, if passed, the module will use one of the words in this structure as the -pollword. This is returned to the app. in r0. - -When an Internet event is triggered, the module scans all registered sockets. -If one is matched, the appropriate bit is set in the pollword. This allows -other bits to be reserved for other things. Note, it is not an error for a -socket to have multiple pollwords associated with it; there is no reason I -can think of for two apps. to share one socket (*why* is another matter, but -it shouldn't be an error); these may both register PWs for them. - -Usage with AcornSSL -------------------- -SocketWatch should only be used with the normal socket numbers, not the ssl -socket handles used by AcornSSL. -However, it can be used for secure sockets with a sequence like: - Socket_Create to get socket normal socket descriptor - AcornSSL_CreateSession to get ssl socket - SocketWatch_Register of normal socket descriptor - -SWIs ----- - -SWI SocketWatch_Register (0x52280) - -On entry: r0 => pollword, 0 for module to allocate one, - r1 = bitmask to set if there's activity - r2 = socket number. - -On exit: r0 => pollword. - If an error is raised by Socket_Ioctl, r0 is => error block - and the socket is not registered. - -If the pollword passed is 0, one allocated from the internal structure will -be returned. Note that this is freed when at the time of deregistering and -may not be used afterwards. - - - -SWI SocketWatch_Deregister (0x52281) - -On entry: r0 = socket, - r1 => pollword. - -On exit: all preserved. - -The socket is no longer watched. If the pollword was allocated by the -module, it is not valid once this call is called. - - - -SWI SocketWatch_AtomicReset (0x52282) - -On entry: r0 => pollword - r1 = new value - -On exit: r0 = old value - r1 preserved. - -This SWI reads from r0, writes r1 to r0, then exits, all with IRQs off, -making it an atomic operation (ie., one which may not be interrupted). It is -a problem with Pollwords in that they're used by IRQ or Callback code, yet -read and reset by usermode code which can't disable IRQs easily. This -removes the problem where the app. reads the PW, IRQ routine sets a couple of -bits, then the forground resets it. - - - -SWI SocketWatch_AllocPW (0x52283) - -On entry: - - -On exit: r0 => 4 bytes of RAM which may be released by SWI -SocketWatch_DeallocPW. - -ATM, this SWI claims four bytes of RMA; this isn't efficient, and may be -changed in later releases. The SWI is provided for convenience's sake. - - - -SWI SocketWatch_DeallocPW (0x52284) - -On entry: r0 => pollword, as allocated by SWI SocketWatch_AllocPW. - -On exit: all preserved. - -ATM this calls OS_Module 7 to free the word. |