Zum Inhalt

Socket API Reference

Der Typ Socket ist der Hauptclient, der die Verbindung zum Socket.IO-Server verwaltet.

Inhaltsverzeichnis

Erstellung

New

func New(rawURL string, options ...Options) *Socket

Erstellt eine neue Socket-Instanz und stellt die Verbindung zum Server her.

Parameter: - rawURL (string): URL des Socket.IO-Servers. Kann das Schema ws:// oder http:// verwenden (wird automatisch zu WebSocket konvertiert) - options (Options, optional): Client-Konfiguration

Rückgabewert: - *Socket: Client-Instanz

Beispiel:

// Grundlegende Verbindung
client := socketio.New("ws://localhost:3000")

// Mit Optionen
client := socketio.New("ws://localhost:3000", socketio.Options{
  Auth: map[string]interface{}{
    "token": "abc123",
  },
  ReconnectAttempts: 5,
  Timeout: 30 * time.Second,
})

Verbindungsmethoden

Close

func (s *Socket) Close() error

Schließt die Verbindung zum Server und gibt alle Ressourcen frei.

Rückgabewert: - error: Fehler, falls die Operation fehlschlägt

Beispiel:

defer client.Close()

// Oder manuell
if err := client.Close(); err != nil {
  fmt.Printf("Fehler beim Schließen: %v\n", err)
}

Ereignismethoden

On

func (s *Socket) On(event string, handler EventHandler)

Registriert einen Handler zum Abhören eines bestimmten Ereignisses im Standard-Namespace (/).

Parameter: - event (string): Ereignisname - handler (EventHandler): Funktion, die beim Empfang des Ereignisses ausgeführt wird

Beispiel:

client.On("message", func(data ...interface{}) {
  fmt.Printf("Nachricht: %v\n", data[0])
})

client.On("user-joined", func(data ...interface{}) {
  username := data[0].(string)
  fmt.Printf("%s ist beigetreten\n", username)
})

OnConnect

func (s *Socket) OnConnect(handler func())

Registriert einen Handler, der ausgeführt wird, wenn die Verbindung erfolgreich hergestellt wurde.

Parameter: - handler (func()): Funktion, die beim Verbinden ausgeführt wird

Beispiel:

client.OnConnect(func() {
  fmt.Println("Verbunden")
  client.Emit("join-room", "sala-1")
})

OnDisconnect

func (s *Socket) OnDisconnect(handler func(reason string))

Registriert einen Handler, der ausgeführt wird, wenn die Verbindung geschlossen wird.

Parameter: - handler (func(reason string)): Funktion, die den Grund für die Trennung erhält

Beispiel:

client.OnDisconnect(func(reason string) {
  fmt.Printf("Getrennt: %s\n", reason)

  if reason == "io server disconnect" {
    fmt.Println("Der Server hat die Verbindung geschlossen")
  }
})

OnError

func (s *Socket) OnError(handler func(err error))

Registriert einen Handler, der bei einem Fehler ausgeführt wird.

Parameter: - handler (func(err error)): Funktion, die den Fehler erhält

Beispiel:

client.OnError(func(err error) {
  fmt.Printf("Fehler: %v\n", err)
})

OnReconnectAttempt

func (s *Socket) OnReconnectAttempt(handler func(attempt int))

Registriert einen Handler, der vor jedem Wiederverbindungsversuch ausgeführt wird.

Parameter: - handler (func(attempt int)): Funktion, die die Versuchsnummer erhält

Beispiel:

client.OnReconnectAttempt(func(attempt int) {
  fmt.Printf("Wiederverbindungsversuch #%d\n", attempt)
})

OnReconnect

func (s *Socket) OnReconnect(handler func(attempt int))

Registriert einen Handler, der bei erfolgreicher Wiederverbindung ausgeführt wird.

Parameter: - handler (func(attempt int)): Funktion, die die Anzahl der Versuche erhält, die zur Wiederverbindung benötigt wurden

Beispiel:

client.OnReconnect(func(attempt int) {
  fmt.Printf("Wiederverbunden nach %d Versuchen\n", attempt)
})

OnReconnectError

func (s *Socket) OnReconnectError(handler func(err error))

Registriert einen Handler, der ausgeführt wird, wenn ein Wiederverbindungsversuch fehlschlägt.

Parameter: - handler (func(err error)): Funktion, die den Fehler erhält

Beispiel:

client.OnReconnectError(func(err error) {
  fmt.Printf("Fehler bei Wiederverbindung: %v\n", err)
})

OnReconnectFailed

func (s *Socket) OnReconnectFailed(handler func())

Registriert einen Handler, der ausgeführt wird, wenn alle Wiederverbindungsversuche fehlschlagen.

Parameter: - handler (func()): Funktion, die ausgeführt wird, wenn die Wiederverbindung endgültig fehlschlägt

Beispiel:

client.OnReconnectFailed(func() {
  fmt.Println("Wiederverbindung nicht möglich")
  notifyUser("Verbindung verloren")
})

Sendemethoden

Emit

func (s *Socket) Emit(event string, data ...interface{}) error

Sendet ein Ereignis an den Server im Standard-Namespace (/).

Parameter: - event (string): Ereignisname - data (...interface{}): Zu sendende Argumente (können mehrere sein)

Rückgabewert: - error: Fehler, falls die Operation fehlschlägt

Beispiel:

// Ein Argument
client.Emit("message", "Hallo Welt")

// Mehrere Argumente
client.Emit("user-action", "login", map[string]interface{}{
  "username": "juan",
  "timestamp": time.Now().Unix(),
})

// Fehlerbehandlung
if err := client.Emit("important", data); err != nil {
  fmt.Printf("Fehler beim Senden: %v\n", err)
}

EmitWithAck

func (s *Socket) EmitWithAck(event string, ack AckCallback, data ...interface{}) error

Sendet ein Ereignis und wartet auf eine Antwort (Acknowledgment) vom Server.

Parameter: - event (string): Ereignisname - ack (AckCallback): Callback-Funktion, die die Antwort erhält - data (...interface{}): Zu sendende Argumente

Rückgabewert: - error: Fehler, falls die Operation fehlschlägt

Beispiel:

client.EmitWithAck("get-user", func(response ...interface{}) {
  if len(response) == 0 {
    fmt.Println("Keine Antwort erhalten (Timeout)")
    return
  }

  user := response[0].(map[string]interface{})
  fmt.Printf("Benutzer: %v\n", user)
}, "user-123")

// Mit konfiguriertem Timeout
client := socketio.New("ws://localhost:3000", socketio.Options{
  AckTimeout: 5 * time.Second,
})

client.EmitWithAck("slow-operation", func(response ...interface{}) {
  if response == nil {
    fmt.Println("Timeout: Server hat nicht rechtzeitig geantwortet")
    return
  }
  fmt.Println("Antwort:", response[0])
}, "datos")

Statusmethoden

IsConnected

func (s *Socket) IsConnected() bool

Gibt zurück, ob der Client derzeit mit dem Server verbunden ist.

Rückgabewert: - bool: true wenn verbunden, false andernfalls

Beispiel:

if client.IsConnected() {
  client.Emit("ping")
} else {
  fmt.Println("Keine Verbindung")
}

GetState

func (s *Socket) GetState() ConnectionState

Gibt den aktuellen Status der Verbindung zurück.

Rückgabewert: - ConnectionState: Aktueller Verbindungsstatus

Mögliche Zustände: - StateDisconnected (0): Keine Verbindung - StateConnecting (1): Verbindung wird hergestellt - StateConnected (2): Verbunden - StateReconnecting (3): Wiederverbindung wird versucht - StateDisconnecting (4): Verbindung wird geschlossen

Beispiel:

state := client.GetState()

switch state {
case socketio.StateDisconnected:
  fmt.Println("Getrennt")
case socketio.StateConnecting:
  fmt.Println("Verbindung wird hergestellt...")
case socketio.StateConnected:
  fmt.Println("Verbunden")
case socketio.StateReconnecting:
  fmt.Println("Wiederverbindung wird versucht...")
case socketio.StateDisconnecting:
  fmt.Println("Verbindung wird getrennt...")
}

GetReconnectCount

func (s *Socket) GetReconnectCount() int

Gibt die Anzahl der Wiederverbindungsversuche des Clients zurück.

Rückgabewert: - int: Zähler der Wiederverbindungsversuche

Beispiel:

count := client.GetReconnectCount()
fmt.Printf("Wiederverbindungsversuche: %d\n", count)

// In Geschäftslogik verwenden
if count > 3 {
  fmt.Println("Mehrere Wiederverbindungsversuche, überprüfen Sie Ihre Verbindung")
}

Konfigurationsmethoden

Of

func (s *Socket) Of(path string) *Namespace

Gibt eine Namespace-Instanz für den angegebenen Pfad zurück. Wenn der Namespace nicht existiert, wird er erstellt.

Parameter: - path (string): Namespace-Pfad (muss mit / beginnen)

Rückgabewert: - *Namespace: Namespace-Instanz

Beispiel:

// Standard-Namespace
client.On("global-event", handler)

// Benutzerdefinierter Namespace
chat := client.Of("/chat")
chat.On("message", func(data ...interface{}) {
  fmt.Println("Chat-Nachricht:", data[0])
})

chat.Emit("join", "sala-general")

// Mehrere Namespaces
admin := client.Of("/admin")
admin.On("alert", adminHandler)

notifications := client.Of("/notifications")
notifications.On("new", notificationHandler)

Verwandte Typen

EventHandler

type EventHandler func(data ...interface{})

Funktionstyp für Ereignisbehandlung.

AckCallback

type AckCallback func(data ...interface{})

Funktionstyp für Behandlung von Acknowledgment-Antworten.

ConnectionState

type ConnectionState int

const (
  StateDisconnected ConnectionState = iota
  StateConnecting
  StateConnected
  StateReconnecting
  StateDisconnecting
)

Mögliche Verbindungszustände.

Thread-sichere Verwendung

Alle Methoden von Socket sind thread-sicher und können gleichzeitig von mehreren Goroutinen aufgerufen werden.

// Von mehreren Goroutinen senden
for i := 0; i < 10; i++ {
  go func(id int) {
    client.Emit("worker", map[string]interface{}{
      "id": id,
      "data": processData(id),
    })
  }(i)
}

// Ereignisse abhören ist thread-sicher
client.On("result", func(data ...interface{}) {
  // Dieser Handler kann nebenläufig aufgerufen werden
  go processResult(data)
})

Vollständiges Beispiel

package main

import (
  "fmt"
  "time"
  socketio "github.com/arcaela/socket.io-client-go"
)

func main() {
  // Client mit Optionen erstellen
  client := socketio.New("ws://localhost:3000", socketio.Options{
    Auth: map[string]interface{}{
      "token": "secret-token",
    },
    ReconnectAttempts: 5,
    ReconnectDelay:    time.Second,
    ReconnectDelayMax: 5 * time.Second,
    Timeout:           30 * time.Second,
    AckTimeout:        5 * time.Second,
  })
  defer client.Close()

  // Lebenszyklus-Ereignisse
  client.OnConnect(func() {
    fmt.Println("✅ Verbunden")

    // Initiales Ereignis senden
    client.Emit("join", "sala-principal")
  })

  client.OnDisconnect(func(reason string) {
    fmt.Printf("❌ Getrennt: %s\n", reason)
  })

  client.OnError(func(err error) {
    fmt.Printf("⚠️  Fehler: %v\n", err)
  })

  // Wiederverbindungsereignisse
  client.OnReconnectAttempt(func(attempt int) {
    fmt.Printf("🔄 Wiederverbindung wird versucht... (#%d)\n", attempt)
  })

  client.OnReconnect(func(attempt int) {
    fmt.Printf("✅ Wiederverbunden nach %d Versuchen\n", attempt)
  })

  // Benutzerdefinierte Ereignisse
  client.On("message", func(data ...interface{}) {
    fmt.Printf("📩 Nachricht: %v\n", data[0])
  })

  client.On("user-joined", func(data ...interface{}) {
    username := data[0].(string)
    fmt.Printf("👤 %s ist beigetreten\n", username)
  })

  // Mit Acknowledgment senden
  client.EmitWithAck("get-data", func(response ...interface{}) {
    if response == nil {
      fmt.Println("⏱️  Timeout beim Warten auf Antwort")
      return
    }
    fmt.Printf("📦 Daten erhalten: %v\n", response[0])
  }, "request-id-123")

  // Namespaces
  chat := client.Of("/chat")
  chat.On("message", func(data ...interface{}) {
    fmt.Printf("💬 Chat: %v\n", data[0])
  })

  // Status überprüfen
  if client.IsConnected() {
    fmt.Println("Status: Verbunden")
  }

  // Anwendung am Laufen halten
  select {}
}

Siehe auch