New (UdpSocket constructor): Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Template:UdpSocket:New subtitle}}
{{Template:UdpSocket:New subtitle}}


New creates an instance of a UdpSocket object. This object can be used to exchange messages with a remote host using a Janus client socket ([[JANUS DEFINE#type|CLSOCKU]]) port.
New creates an instance of a <var>UdpSocket</var> object. This object can be used to exchange messages with a remote host using a Janus client socket (<var>[[JANUS DEFINE#type|CLSOCKU]]</var>) port.
 
==Syntax==
==Syntax==
{{Template:UdpSocket:New syntax}}
{{Template:UdpSocket:New syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%outUdpSocket</th><td>udpSocket</td></tr>
<tr><th>%outUdpSocket</th>
<td>A <var>UdpSocket</var> object.</td></tr>
 
<tr><th nowrap="true"><var>[%(UdpSocket):]</var></th>
<tr><th nowrap="true"><var>[%(UdpSocket):]</var></th>
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Constructor</var>.</td></tr>
<td>The optional class name in parentheses denotes a <var>[[Notation conventions for methods#Constructors|Constructor]]</var>. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a <var>Constructor</var>.</td></tr>
<tr><th><var>ClientPort</var></th>
<tr><th><var>ClientPort</var></th>
<td>The name of the client UDP socket (CLSOCKU) port. The default is the <var>[[MASTER]]</var> CLSOCKU port, if any is defined. However, if you omit <var class="term">clientport</var> and no <var>MASTER</var> CLSOCKU port is defined, the request is canceled.</td></tr>
<td>The name of the client UDP socket (<var>CLSOCKU</var>) port. The default is the <var>[[MASTER]]</var> <var>CLSOCKU</var> port, if any is defined. However, if you omit <var class="term">clientport</var> and no <var>MASTER</var> <var>CLSOCKU</var> port is defined, the request is canceled.</td></tr>
 
<tr><th><var>LocalHost</var></th>
<tr><th><var>LocalHost</var></th>
<td>The IP address to use for messages sent on the client socket port. If not specified, the default or only IP address of the host on which Model 204 is running is used. This parameter is an alternative to the [[BINDADDR (JANUS DEFINE parameter)|BINDADDR JANUS DEFINE parameter]]. If <var>BINDADDR</var> is specified on the CLSOCKU port used for the UdpSocket, the <var>LocalHost</var> parameter is unnecessary and, if specified, must match the IP address specified on the <var>BINDADDR</var>. If <var>LocalHost</var> or <var>BINDADDR</var> is specified for a UDP socket, only messages sent to that IP address will be received by the UdpSocket object.</td></tr>
<td>The IP address to use for messages sent on the client socket port. If not specified, the default or only IP address of the host on which <var class="product">Model 204</var> is running is used.  
<p>
This parameter is an alternative to the <var>[[BINDADDR (JANUS DEFINE parameter)|BINDADDR]]</var> <var>JANUS DEFINE</var> parameter. If <var>BINDADDR</var> is specified on the <var>CLSOCKU</var> port used for the <var>UdpSocket</var>:
<ul>
<li>The <var>LocalHost</var> parameter is unnecessary.
<li>If  <var>LocalHost</var> value is specified, it must match the IP address specified on the <var>BINDADDR</var>.
</ul></p>
<p>
If <var>LocalHost</var> or <var>BINDADDR</var> is specified for a UDP socket, only messages sent to that IP address will be received by the <var>UdpSocket</var> object.</p></td></tr>
 
<tr><th><var>LocalPort</var></th>
<tr><th><var>LocalPort</var></th>
<td>The UDP port number to use for messages sent to and received from the UdpSocket. If this parameter is not specified, the UDP stack will assign a port number (usually 1024 and higher) to the UdpSocket object. This parameter is most useful when writing a UDP server application that is handled by a single thread (since only one thread can issue a New for a particular UDP port number). Typically a server application will create a UdpSocket for a well-known UDP port number to which clients subsequently send requests. There are some protocols such as SNMP that sometimes send messages from a well-known port number to another server.</td></tr>
<td>The UDP port number to use for messages sent to and received from the new <var>UdpSocket</var>. If this parameter is not specified, the UDP stack will assign a port number (usually 1024 and higher) to the <var>UdpSocket</var> object.  
<p>
This parameter is most useful when writing a UDP server application that is handled by a single thread (since only one thread can issue a <var>New</var> for a particular UDP port number). Typically a server application will create a <var>UdpSocket</var> for a well-known UDP port number to which clients subsequently send requests. There are some protocols such as SNMP that sometimes send messages from a well-known port number to another server.</p></td></tr>
 
<tr><th><var>Host</var></th>
<tr><th><var>Host</var></th>
<td>The target host for messages sent from the UDP socket. This can be an IP address or a host name, the latter being resolved using the [[JANUS NAMESERVER|Janus Domain Name Services support]]. If <var>Host</var> is specified on the <var>New</var> method invocation, it cannot be changed later. If an application wishes to use a UdpSocket to communicate with multiple hosts, it should not specify <var>Host</var> on the New method invocation.</td></tr>
<td>The target host for messages sent from the UDP socket. This can be an IP address or a host name, the latter being resolved using the [[JANUS NAMESERVER|Janus Domain Name Services support]].  
<p>
If <var>Host</var> is specified on the <var>New</var> method invocation, it cannot be changed later. If an application wants to use a <var>UdpSocket</var> to communicate with multiple hosts, it should not specify <var>Host</var> on the <var>New</var> method invocation.</p></td></tr>
 
<tr><th><var>Port</var></th>
<tr><th><var>Port</var></th>
<td>The target port number for messages sent from the UDP port. This must be a number between 1 and 65534. If <var>Port</var> is specified on the <var>New</var> method invocation, it cannot be changed later. If an application wishes to use a UdpSocket to communicate with multiple port numbers, it should not specify <var>Port</var> on the New method invocation.</td></tr>
<td>The target port number for messages sent from the UDP port. This must be a number between 1 and 65534.  
<p>
If <var>Port</var> is specified on the <var>New</var> method invocation, it cannot be changed later. If an application wants to use a <var>UdpSocket</var> to communicate with multiple port numbers, it should not specify <var>Port</var> on the <var>New</var> method invocation.</p></td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<li>While the <var>New</var> method doesn't attempt to communicate with a target host, it can fail with a request canceling error if no <var>CLSOCKU</var> port is available or if the maximum number of connections for a port is exceeded.</li>
<li>While a UDP socket doesn't actually have a connection with anything, a <var>New</var> method uses a logical connection for the port until the <var>UdpSocket</var> object is discarded. This logical connection is counted against the port's maximum connection limit.</li>
<li>As described in [[Object variables#Using New or other Constructors|"Using New or other Constructors"]], <var>New</var> can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is <var>Null</var>:<p class="code">%udpSock = new
%udpSock= %(UdpSocket):new
%udpSock= %udpSock:new
</p></li>
</ul>
==Examples==
==Examples==
<ol>
<li>The following code is a sample server that simply echoes any message sent to it:
<p class="code">b
%message    is longstring
%udpSock    is object udpSocket
%udpSock=new(localPort=1234)
%udpSock:timeout = 0
repeat forever
  %message = %udpSock:receive
  %udpSock:send(%message)
end repeat
end
</p>
<li>The following request sends a message to the server above, and it waits up to one second for a matching response:
<p class="code">b
%time      is string len 32
%message    is longstring
%udpSock    is object udpSocket
%udpSock=new(host='198.242.244.47', port=1234)
%time = %(system):currentTimeString('YYYYMMDDHHMISSXXX')
%udpSock:send(%time)
%udpSock:timeout = 1
repeat forever
  %message = %udpSock:receive
  if %message eq %time then
      printText Ping successful!
      loop end
  end if
  if %message eq <nowiki>''</nowiki> then
      printText No response received for ping
      loop end
  end if
end repeat
end
</p></ol>
==See also==
==See also==
{{Template:UdpSocket:New footer}}
{{Template:UdpSocket:New footer}}

Latest revision as of 18:16, 13 December 2012

Create a UdpSocket object (UdpSocket class)

[Introduced in Sirius Mods 8.0]


New creates an instance of a UdpSocket object. This object can be used to exchange messages with a remote host using a Janus client socket (CLSOCKU) port.

Syntax

%udpSocket = [%(UdpSocket):]New[( [ClientPort= string], [LocalHost= string], - [LocalPort= number], [Host= string], - [Port= number])]

Syntax terms

%outUdpSocket A UdpSocket object.
[%(UdpSocket):] The optional class name in parentheses denotes a Constructor. See "Usage notes", below, for more information about invoking a Constructor.
ClientPort The name of the client UDP socket (CLSOCKU) port. The default is the MASTER CLSOCKU port, if any is defined. However, if you omit clientport and no MASTER CLSOCKU port is defined, the request is canceled.
LocalHost The IP address to use for messages sent on the client socket port. If not specified, the default or only IP address of the host on which Model 204 is running is used.

This parameter is an alternative to the BINDADDR JANUS DEFINE parameter. If BINDADDR is specified on the CLSOCKU port used for the UdpSocket:

  • The LocalHost parameter is unnecessary.
  • If LocalHost value is specified, it must match the IP address specified on the BINDADDR.

If LocalHost or BINDADDR is specified for a UDP socket, only messages sent to that IP address will be received by the UdpSocket object.

LocalPort The UDP port number to use for messages sent to and received from the new UdpSocket. If this parameter is not specified, the UDP stack will assign a port number (usually 1024 and higher) to the UdpSocket object.

This parameter is most useful when writing a UDP server application that is handled by a single thread (since only one thread can issue a New for a particular UDP port number). Typically a server application will create a UdpSocket for a well-known UDP port number to which clients subsequently send requests. There are some protocols such as SNMP that sometimes send messages from a well-known port number to another server.

Host The target host for messages sent from the UDP socket. This can be an IP address or a host name, the latter being resolved using the Janus Domain Name Services support.

If Host is specified on the New method invocation, it cannot be changed later. If an application wants to use a UdpSocket to communicate with multiple hosts, it should not specify Host on the New method invocation.

Port The target port number for messages sent from the UDP port. This must be a number between 1 and 65534.

If Port is specified on the New method invocation, it cannot be changed later. If an application wants to use a UdpSocket to communicate with multiple port numbers, it should not specify Port on the New method invocation.

Usage notes

  • While the New method doesn't attempt to communicate with a target host, it can fail with a request canceling error if no CLSOCKU port is available or if the maximum number of connections for a port is exceeded.
  • While a UDP socket doesn't actually have a connection with anything, a New method uses a logical connection for the port until the UdpSocket object is discarded. This logical connection is counted against the port's maximum connection limit.
  • As described in "Using New or other Constructors", New can be invoked with no object, with an explicit class name, or with an object variable in the class, even if that object is Null:

    %udpSock = new %udpSock= %(UdpSocket):new %udpSock= %udpSock:new

Examples

  1. The following code is a sample server that simply echoes any message sent to it:

    b %message is longstring %udpSock is object udpSocket %udpSock=new(localPort=1234) %udpSock:timeout = 0 repeat forever %message = %udpSock:receive %udpSock:send(%message) end repeat end

  2. The following request sends a message to the server above, and it waits up to one second for a matching response:

    b %time is string len 32 %message is longstring %udpSock is object udpSocket %udpSock=new(host='198.242.244.47', port=1234) %time = %(system):currentTimeString('YYYYMMDDHHMISSXXX') %udpSock:send(%time) %udpSock:timeout = 1 repeat forever %message = %udpSock:receive if %message eq %time then printText Ping successful! loop end end if if %message eq '' then printText No response received for ping loop end end if end repeat end

See also