Blitz3D+ Command Reference

CloseUDPStream udp_stream

Parameters

udp_stream - a UDP stream handle returned by CreateUDPStream

Description

Closes a UDP stream and releases its port.

Call this when a stream has done its job - when the player leaves the multiplayer game, or your netcode shuts down. The port the stream was bound to is freed immediately, so it can be bound again straight away (the example proves it by rebinding the same port).

The handle becomes invalid the moment the stream is closed: using it afterwards is an error (in debug mode the runtime stops with "UDP Stream does not exist"). Anything received but not yet read is discarded, and so is anything written but not yet fired with SendUDPMsg - flush your goodbyes before hanging up.

Blitz3D+ closes any UDP streams still open when the program ends, but closing them yourself keeps ports free for the rest of the machine while your game runs on.

See also: CreateUDPStream, SendUDPMsg, RecvUDPMsg, CloseTCPStream.

Example

; CloseUDPStream Example
; ----------------------

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

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

host=CreateUDPStream(5402)
If host=0 Then
    Print "Could not bind port 5402 (it may be in use)"
Else
    Print "Host: listening on port "+UDPStreamPort(host)

    player=CreateUDPStream()
    If player=0 Then
        Print "Player: could not create a UDP stream"
    Else
        ; A quick exchange to show both streams are alive
        WriteLine player,"Last message before shutdown"
        SendUDPMsg player,loopback,5402
        UDPTimeouts 500
        If RecvUDPMsg(host)<>0 Then
            Print "Host: received '"+ReadLine$(host)+"'"
        EndIf

        ; CloseUDPStream shuts the stream down and releases its
        ; port - the handle must not be used after this
        CloseUDPStream player
        Print "Player: stream closed"
    EndIf
    CloseUDPStream host
    Print "Host: stream closed, port 5402 released"

    ; The freed port can be bound again straight away
    again=CreateUDPStream(5402)
    If again=0 Then
        Print "Could not rebind port 5402"
    Else
        Print "Rebound port "+UDPStreamPort(again)+" - CloseUDPStream freed it"
        CloseUDPStream again
    EndIf
EndIf

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

End

Index