Struct socketioxide::handler::extract::SocketRef

pub struct SocketRef<A: Adapter = LocalAdapter>(/* private fields */);

An Extractor that returns a reference to a Socket.

Implementations

impl<A: Adapter> SocketRef<A>

pub fn disconnect(self) -> Result<(), SendError>

Disconnect the socket from the current namespace,

It will also call the disconnect handler if it is set.

Methods from Deref<Target = Socket<A>>

pub fn on<H, T>(&self, event: impl Into<Cow<'static, str>>, handler: H)

where H: MessageHandler<A, T>, T: Send + Sync + 'static,

Registers a MessageHandler for the given event.

• See the message module doc for more details on message handler.
• See the extract module doc for more details on available extractors.

Simple example with a sync closure:

#[derive(Debug, Serialize, Deserialize)]
struct MyData {
    name: String,
    age: u8,
}

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    // Register a handler for the "test" event and extract the data as a `MyData` struct
    // With the Data extractor, the handler is called only if the data can be deserialized as a `MyData` struct
    // If you want to manage errors yourself you can use the TryData extractor
    socket.on("test", |socket: SocketRef, Data::<MyData>(data)| {
        println!("Received a test message {:?}", data);
        socket.emit("test-test", MyData { name: "Test".to_string(), age: 8 }).ok(); // Emit a message to the client
    });
});

Example with a closure and an acknowledgement + binary data:

#[derive(Debug, Serialize, Deserialize)]
struct MyData {
    name: String,
    age: u8,
}

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    // Register an async handler for the "test" event and extract the data as a `MyData` struct
    // Extract the binary payload as a `Vec<Vec<u8>>` with the Bin extractor.
    // It should be the last extractor because it consumes the request
    socket.on("test", |socket: SocketRef, Data::<MyData>(data), ack: AckSender, Bin(bin)| async move {
        println!("Received a test message {:?}", data);
        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
        ack.bin(bin).send(data).ok(); // The data received is sent back to the client through the ack
        socket.emit("test-test", MyData { name: "Test".to_string(), age: 8 }).ok(); // Emit a message to the client
    });
});

pub fn on_disconnect<C, T>(&self, callback: C)

where C: DisconnectHandler<A, T> + Send + Sync + 'static, T: Send + Sync + 'static,

Registers a disconnect handler.

You can register only one disconnect handler per socket. If you register multiple handlers, only the last one will be used.

• See the disconnect module doc for more details on disconnect handler.
• See the extract module doc for more details on available extractors.

The callback will be called when the socket is disconnected from the server or the client or when the underlying connection crashes. A DisconnectReason is passed to the callback to indicate the reason for the disconnection.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef| async move {
        // Close the current socket
        socket.disconnect().ok();
    });
    socket.on_disconnect(|socket: SocketRef, reason: DisconnectReason| async move {
        println!("Socket {} on ns {} disconnected, reason: {:?}", socket.id, socket.ns(), reason);
    });
});

pub fn emit( &self, event: impl Into<Cow<'static, str>>, data: impl Serialize ) -> Result<(), SendError>

Emits a message to the client

Errors

• If the data cannot be serialized to JSON, a SendError::Serialize is returned.
• If the packet buffer is full, a SendError::InternalChannelFull is returned. See SocketIoBuilder::max_buffer_size option for more infos on internal buffer config

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        // Emit a test message to the client
        socket.emit("test", data).ok();
    });
});

pub async fn emit_with_ack<V>( &self, event: impl Into<Cow<'static, str>>, data: impl Serialize ) -> Result<AckResponse<V>, AckError>

where V: DeserializeOwned + Send + Sync + 'static,

Emits a message to the client and wait for acknowledgement.

The acknowledgement has a timeout specified in the config (5s by default) (see SocketIoBuilder::ack_timeout) or with the timeout() operator.

Errors

• If the data cannot be serialized to JSON, a AckError::Serialize is returned.
• If the packet could not be sent, a AckError::SendChannel is returned.
• In case of timeout an AckError::Timeout is returned.

Example without custom timeout

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        // Emit a test message and wait for an acknowledgement with the timeout specified in the config
        match socket.emit_with_ack::<Value>("test", data).await {
            Ok(ack) => println!("Ack received {:?}", ack),
            Err(err) => println!("Ack error {:?}", err),
        }
   });
});

pub fn join(&self, rooms: impl RoomParam) -> Result<(), A::Error>

Joins the given rooms.

If the room does not exist, it will be created.

Errors

When using a distributed adapter, it can return an Adapter::Error which is mostly related to network errors. For the default LocalAdapter it is always an Infallible error

pub fn leave(&self, rooms: impl RoomParam) -> Result<(), A::Error>

Leaves the given rooms.

If the room does not exist, it will do nothing

Errors

When using a distributed adapter, it can return an Adapter::Error which is mostly related to network errors. For the default LocalAdapter it is always an Infallible error

pub fn leave_all(&self) -> Result<(), A::Error>

Leaves all rooms where the socket is connected.

Errors

When using a distributed adapter, it can return an Adapter::Error which is mostly related to network errors. For the default LocalAdapter it is always an Infallible error

pub fn rooms(&self) -> Result<Vec<Room>, A::Error>

Gets all rooms where the socket is connected.

Errors

When using a distributed adapter, it can return an Adapter::Error which is mostly related to network errors. For the default LocalAdapter it is always an Infallible error

pub fn to(&self, rooms: impl RoomParam) -> Operators<A>

Selects all clients in the given rooms except the current socket.

If you want to include the current socket, use the within() operator.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        let other_rooms = "room4".to_string();
        // In room1, room2, room3 and room4 except the current
        socket
            .to("room1")
            .to(["room2", "room3"])
            .to(vec![other_rooms])
            .emit("test", data);
    });
});

pub fn within(&self, rooms: impl RoomParam) -> Operators<A>

Selects all clients in the given rooms.

It does include the current socket contrary to the to() operator.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        let other_rooms = "room4".to_string();
        // In room1, room2, room3 and room4 including the current socket
        socket
            .within("room1")
            .within(["room2", "room3"])
            .within(vec![other_rooms])
            .emit("test", data);
    });
});

pub fn except(&self, rooms: impl RoomParam) -> Operators<A>

Filters out all clients selected with the previous operators which are in the given rooms.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("register1", |socket: SocketRef, Data::<Value>(data)| async move {
        socket.join("room1");
    });
    socket.on("register2", |socket: SocketRef, Data::<Value>(data)| async move {
        socket.join("room2");
    });
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        // This message will be broadcast to all clients in the Namespace
        // except for ones in room1 and the current socket
        socket.broadcast().except("room1").emit("test", data);
    });
});

pub fn local(&self) -> Operators<A>

Broadcasts to all clients only connected on this node (when using multiple nodes). When using the default in-memory LocalAdapter, this operator is a no-op.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        // This message will be broadcast to all clients in this namespace and connected on this node
        socket.local().emit("test", data);
    });
});

pub fn timeout(&self, timeout: Duration) -> Operators<A>

Sets a custom timeout when sending a message with an acknowledgement.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
   socket.on("test", |socket: SocketRef, Data::<Value>(data), Bin(bin)| async move {
      // Emit a test message in the room1 and room3 rooms, except for the room2 room with the binary payload received, wait for 5 seconds for an acknowledgement
      socket.to("room1")
            .to("room3")
            .except("room2")
            .bin(bin)
            .timeout(Duration::from_secs(5))
            .emit_with_ack::<Value>("message-back", data).unwrap().for_each(|ack| async move {
               match ack {
                   Ok(ack) => println!("Ack received {:?}", ack),
                   Err(err) => println!("Ack error {:?}", err),
               }
            }).await;
   });
});

pub fn bin(&self, binary: Vec<Vec<u8>>) -> Operators<A>

Adds a binary payload to the message.

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data), Bin(bin)| async move {
        // This will send the binary payload received to all clients in this namespace with the test message
        socket.bin(bin).emit("test", data);
    });
});

pub fn broadcast(&self) -> Operators<A>

Broadcasts to all clients without any filtering (except the current socket).

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef| {
    socket.on("test", |socket: SocketRef, Data::<Value>(data)| async move {
        // This message will be broadcast to all clients in this namespace
        socket.broadcast().emit("test", data);
    });
});

pub fn disconnect(self: Arc<Self>) -> Result<(), SendError>

Disconnects the socket from the current namespace,

It will also call the disconnect handler if it is set.

pub fn ns(&self) -> &str

Gets the current namespace path.

pub fn req_parts(&self) -> &Parts

Gets the request info made by the client to connect

Note that the extensions field will be empty and will not contain extensions set in the previous http layers for requests initialized with ws transport.

It is because http::Extensions is not cloneable and is needed for ws upgrade.

pub fn transport_type(&self) -> TransportType

Gets the TransportType used by the client to connect with this Socket

It can also be accessed as an extractor:

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef, transport: TransportType| {
    assert_eq!(socket.transport_type(), transport);
});

pub fn protocol(&self) -> ProtocolVersion

Gets the socket.io ProtocolVersion used by the client to connect with this Socket

It can also be accessed as an extractor:

Example

let (_, io) = SocketIo::new_svc();
io.ns("/", |socket: SocketRef, v: ProtocolVersion| {
    assert_eq!(socket.protocol(), v);
});

Trait Implementations

impl<A: Adapter> Deref for SocketRef<A>

type Target = Socket<A>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<A: Adapter> FromConnectParts<A> for SocketRef<A>

type Error = Infallible

The error type returned by the extractor

fn from_connect_parts( s: &Arc<Socket<A>>, _: &Option<String> ) -> Result<Self, Infallible>

Extract the arguments from the connect event. If it fails, the handler is not called

impl<A: Adapter> FromDisconnectParts<A> for SocketRef<A>

type Error = Infallible

The error type returned by the extractor

fn from_disconnect_parts( s: &Arc<Socket<A>>, _: DisconnectReason ) -> Result<Self, Infallible>

Extract the arguments from the disconnect event. If it fails, the handler is not called

impl<A: Adapter> FromMessageParts<A> for SocketRef<A>

type Error = Infallible

The error type returned by the extractor

fn from_message_parts( s: &Arc<Socket<A>>, _: &mut Value, _: &mut Vec<Vec<u8>>, _: &Option<i64> ) -> Result<Self, Infallible>

Extract the arguments from the message event. If it fails, the handler is not called.