From WikiChip
Difference between revisions of "mirc/on events/on sockread"
< mirc‎ | on events

m (→‎Parameters: Link access levels)
 
(19 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{mirc title|On Sockread - Events}}
 
The '''ON SOCKREAD''' triggers when there is info waiting to be read on the specified TCP socket connection. You can read this info using the {{mIRC|/sockread}} command.
 
The '''ON SOCKREAD''' triggers when there is info waiting to be read on the specified TCP socket connection. You can read this info using the {{mIRC|/sockread}} command.
  
−
'''Note''': If this event triggers but no /sockread is performed to attempt to read the buffer, it is assumed that no script exists that is handling this buffer, so it is cleared and the info it contained is lost.
+
'''Note''': If this event triggers but no {{mIRC|/sockread}} is performed to attempt to read the buffer, it is assumed that no script exists that is handling this buffer, so it is cleared and the info it contained is lost.
−
 
 
−
mIRC in general only understand $crlf terminated line. With socket, mIRC will stop at {{mIRC|$lf}} terminated line and any {{mIRC|$cr}} before a $lf is removed.
 
  
 
== Synopsis ==
 
== Synopsis ==
Line 9: Line 8:
  
 
== Parameters ==
 
== Parameters ==
−
<span style="display: inline-block; width: 105px;">'''<matchtext>'''</span>The name of the socket you want event to trigger on.
+
<span style="display: inline-block; width: 105px;"> '''<level>'''</span>The corresponding {{mIRC|access levels}} for the event to trigger.
 +
 
 +
<span style="display: inline-block; width: 105px;">'''<matchtext>'''</span>The name of the socket you want the event to trigger on.
  
 
<span style="display: inline-block; width: 105px;">'''<commands>'''</span>The commands to be performed when the event listener's criteria is met.
 
<span style="display: inline-block; width: 105px;">'''<commands>'''</span>The commands to be performed when the event listener's criteria is met.
Line 15: Line 16:
 
== Connection State ==
 
== Connection State ==
  
−
You should be checking for $sockerr before reading data, here is a list of the possible value for $sockerr in the on SOCKREAD event:
+
It's important to check the value of {{mIRC|$sockerr}} to determine if any connection errors occurred and handle that case. Here is a list of possible values returned by $sockerr in the on SOCKREAD event:
  
 
* '''0''' - Data received correctly.
 
* '''0''' - Data received correctly.
−
* '''3''' - Error on connected socket occurred, $sock().wsmsg will contain a more specific error message.
+
* '''3''' - Error occurred on connected socket: $sock($sockname).wsmsg will contain a more specific error message.
  
 
== Examples ==
 
== Examples ==
  
 +
You can find more information and examples in the {{mIRC|/sockread}} command page.
 +
 +
Here is a basic outline:
 
<source lang="mirc">
 
<source lang="mirc">
−
on *:sockread:name:{
+
on *:sockread:example:{
−
   if ($sockerr) { echo -s An error occured while trying to read data: $sock($sockname).wsmsg | return }
+
 
 +
  ;if an error occurred ($sockerr is not 0)
 +
   if ($sockerr) {
 +
    echo -s An error occurred: $sock($sockname).wsmsg
 +
  }
 +
 
 +
  ;no error occurred ($sockerr was 0)
 
   else {
 
   else {
−
     sockread %a
+
 
−
     echo -s rcvd: %a
+
    ;perform commands related to reading the data
 +
 
 +
     ;declare %r as a local variable for use in /sockread
 +
    var %r
 +
 
 +
    ;read a line into %r from the buffer (this variable is subject to mIRC's Line Length Limit - see the /sockread page for more information)
 +
    sockread %r
 +
 
 +
     ;do things with %r, such as checking its value or extracting parts to output later
 +
 
 
   }
 
   }
 
}
 
}
 
</source>
 
</source>
−
'''Note''': A single /sockread may not be enough to read the entire buffer. You should keep reading until $sockbr (bytes read) is set to zero. This is far faster than letting mIRC re-trigger the event. If your script does not read the whole buffer, the on sockread event is re-triggered if:
 
−
 
−
* a) you were reading into a &binvar.
 
−
* b) you were reading into a %var and there is still a terminated line in the buffer waiting to be read.
 
−
 
−
You can find an example showing how to do that {{mIRC|/sockread#Example|here}}
 
  
 
== Compatibility ==
 
== Compatibility ==
Line 42: Line 55:
  
 
== See Also ==
 
== See Also ==
−
* {{mIRC|List of on events|mIRC events}}
+
* {{mirc|on events/on sockopen|on sockopen}}
 +
* {{mirc|on events/on sockwrite|on sockwrite}}
 +
* {{mirc|on events/on socklisten|on socklisten}}
 +
* {{mirc|on events/on sockclose|on sockclose}}
 +
* {{mIRC|/sockopen}}
 
* {{mIRC|/sockwrite}}
 
* {{mIRC|/sockwrite}}
 +
* {{mIRC|/sockread}}
 
* {{mIRC|/sockclose}}
 
* {{mIRC|/sockclose}}
−
* {{mIRC|/sockread}}
 
 
* {{mIRC|/sockaccept}}
 
* {{mIRC|/sockaccept}}
 
* {{mIRC|/sockpause}}
 
* {{mIRC|/sockpause}}
 +
* {{mIRC|$sockname}}
 
* {{mIRC|$sock}}
 
* {{mIRC|$sock}}
 
* {{mIRC|$sockbr}}
 
* {{mIRC|$sockbr}}
 
* {{mIRC|$sockerr}}
 
* {{mIRC|$sockerr}}
  
−
[[Category:MIRC on events]]
+
[[Category:mIRC on events|sockread]]

Latest revision as of 07:13, 6 February 2024

Commands & Identifiers
Basics
Events
Matching Tools
Data Storage
Control Structures
GUI Scripting
Sockets
Advanced Scripting
Additional Resources
Security
Other
v · d · e

The ON SOCKREAD triggers when there is info waiting to be read on the specified TCP socket connection. You can read this info using the /sockread command.

Note: If this event triggers but no /sockread is performed to attempt to read the buffer, it is assumed that no script exists that is handling this buffer, so it is cleared and the info it contained is lost.

Synopsis[edit]

ON <level>:SOCKREAD:<matchtext>:<commands>

Parameters[edit]

<level>The corresponding access levels for the event to trigger.

<matchtext>The name of the socket you want the event to trigger on.

<commands>The commands to be performed when the event listener's criteria is met.

Connection State[edit]

It's important to check the value of $sockerr to determine if any connection errors occurred and handle that case. Here is a list of possible values returned by $sockerr in the on SOCKREAD event:

  • 0 - Data received correctly.
  • 3 - Error occurred on connected socket: $sock($sockname).wsmsg will contain a more specific error message.

Examples[edit]

You can find more information and examples in the /sockread command page.

Here is a basic outline: 

on *:sockread:example:{
 
  ;if an error occurred ($sockerr is not 0)
  if ($sockerr) {
    echo -s An error occurred: $sock($sockname).wsmsg
  }
 
  ;no error occurred ($sockerr was 0)
  else {
 
    ;perform commands related to reading the data
 
    ;declare %r as a local variable for use in /sockread
    var %r
 
    ;read a line into %r from the buffer (this variable is subject to mIRC's Line Length Limit - see the /sockread page for more information)
    sockread %r
 
    ;do things with %r, such as checking its value or extracting parts to output later
 
  }
}

Compatibility[edit]

Added: mIRC v3.5
Added on: 07 Aug 1995
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.


See Also[edit]

Retrieved from "https://en.wikichip.org/w/index.php?title=mirc/on_events/on_sockread&oldid=102265"