Blitz3D+ Command Reference

SendUDPMsg udp_stream,dest_ip[,dest_port]

Parameters

udp_stream - a UDP stream handle returned by CreateUDPStream

dest_ip - destination IP address as a packed integer

dest_port (optional) - destination port; 0 (default) - but always pass a real port, see below

Description

Sends everything written to a UDP stream as one packet to a destination IP and port.

A UDP stream works like an outbox: the stream write commands (WriteLine, WriteInt, WriteString, ...) quietly collect data in a buffer, and nothing travels until SendUDPMsg fires the whole buffer as a single packet. The buffer is then cleared, ready for the next message. So the pattern is: write one game message, send, repeat - the receiving end gets it in one piece from a single RecvUDPMsg.

dest_ip is a packed integer of the kind every networking command trades in - from HostIP after a name lookup, from RecvUDPMsg/UDPMsgIP to answer a sender, or built by hand (the loopback address 127.0.0.1 is (127 Shl 24) Or 1). DottedIP turns one back into readable text.

Because this is UDP, sending is not delivery: the packet can be lost on the way and no error is reported. Design game messages so a lost one is survivable - send fresh state regularly rather than one-off events.

Always pass dest_port explicitly. Leaving it off is meant to reuse the stream's own port number, but a long-standing byte-order quirk in the engine scrambles the defaulted port, so the packet quietly goes to the wrong place unless you say where.

See also: RecvUDPMsg, CreateUDPStream, UDPMsgIP, UDPMsgPort, DottedIP.

Example

; SendUDPMsg Example
; ------------------

; This program is both ends of a UDP conversation at once: two
; streams on this machine swap packets over the loopback address.

; The loopback address 127.0.0.1 as a packed integer
loopback=(127 Shl 24) Or 1

host=CreateUDPStream(5403)
If host=0 Then
    Print "Could not bind port 5403 (it may be in use)"
Else
    player=CreateUDPStream()
    If player=0 Then
        Print "Player: could not create a UDP stream"
    Else
        ; Everything written to the stream is held in a buffer...
        WriteLine player,"Two lines of chat"
        WriteLine player,"travelling together"
        Print "Player: wrote two lines - nothing has been sent yet"

        ; ...until SendUDPMsg fires the whole buffer as ONE packet.
        ; Always give dest_port - see the SendUDPMsg help page.
        SendUDPMsg player,loopback,5403
        Print "Player: SendUDPMsg fired them as one packet to "+DottedIP$(loopback)+":5403"

        ; The host receives a single packet holding both lines
        UDPTimeouts 500
        If RecvUDPMsg(host)=0 Then
            Print "Host: no packet arrived"
        Else
            Print "Host: one packet arrived ("+ReadAvail(host)+" bytes)"
            Print "Host: line 1 = '"+ReadLine$(host)+"'"
            Print "Host: line 2 = '"+ReadLine$(host)+"'"
        EndIf

        ; A second send makes a second, separate packet
        WriteLine player,"Fresh packet"
        SendUDPMsg player,loopback,5403
        If RecvUDPMsg(host)<>0 Then
            Print "Host: next packet = '"+ReadLine$(host)+"'"
        EndIf

        CloseUDPStream player
    EndIf
    CloseUDPStream host
EndIf

Print ""
Print "Press any key to close the example"
WaitKey

End

Index