UDP Communication

Definition

[h2]qg.createUDPSocket(Object object) (1117+)

• Description

  Creates a UDP socket instance.

• Parameters

  Parameter	Type	Mandatory	Description
  object	Object/string	No	If no input parameter is specified, a UDP socket of the udp4 type using IPv4 is created by default, with address reuse disabled. If the input parameter is of the string type, a UDP socket of the specified type (udp4 or udp6) is created. If the input parameter is of the object type, a UDP socket of the specified type is created and whether to allow address reuse is specified. For details, please refer to Parameters in object.

  • Parameters in object

    Parameter	Type	Mandatory	Description
    type	string	Yes	Type of the created UDP socket. The value can be udp4 or udp6.
    reuseAddr	boolean	Yes	Indicates whether to allow port reuse when calling the bind() function.

• Returns

  A UDP socket instance.

• Sample code

  const udp4 = qg.createUDPSocket('udp4');
  const udp6 = qg.createUDPSocket({
    type: "udp6",
    reuseAddr: true
  });

[h2]UDPSocket.bind(number port) (1117+)

• Description

  Binds to an available port that is randomly allocated by the system or a specified port.

• Parameters

  Parameter	Type	Mandatory	Description
  port	number	No	Port to be bound. If this parameter is not specified, an available port randomly allocated by the system is returned.

• Returns

  A port that is successfully bound.

• Sample code

  const udp = qg.createUDPSocket();
  const port = udp.bind()

[h2]UDPSocket.setTTL(number ttl) (1117+)

• Description

  Sets the IP_TTL socket option to define the maximum number of hops allowed during the transmission of an IP data packet.

• Parameters

  Parameter	Type	Mandatory	Description
  ttl	number	Yes	The value of this parameter ranges from 0 to 255.

• Sample code

  const udp = qg.createUDPSocket();
  udp.onListening(function () {
    udp.setTTL(64);
  )}
  udp.bind();

[h2]UDPSocket.send(Object object) (1117+)

• Description

  Sends a message to the specified IP address and port.

• Parameters

  Parameter	Type	Mandatory	Description
  address	string	Yes	Address to which a message is sent.
  port	number	Yes	Port to which a message is sent.
  message	string/ArrayBuffer	Yes	Data to be sent.
  offset	number	No	Offset of the data to be sent. This parameter is valid only when message is of the ArrayBuffer type. The default value is 0.
  length	number	No	Length of the data to be sent. This parameter is valid only when message is of the ArrayBuffer type. The default value is message.byteLength.

• Sample code

  const udp = qg.createUDPSocket();
  udp.bind();
  udp.send({
    address: '192.168.193.2',
    port: 8848,
    message: 'hello, how are you'
  })

[h2]UDPSocket.connect(Object object) (1117+)

• Description

  Preconnects to the specified IP address and port. This method must be used together with the UDPSocket.write(Object object) method.

• Parameters

  Parameter	Type	Mandatory	Description
  address	string	Yes	Address to which a message is sent.
  port	number	Yes	Port to which a message is sent.

• Sample code

  const udp = qg.createUDPSocket();
  udp.bind();
  udp.connect({
    address: '192.168.193.2',
    port: 8848,
  })
  udp.write({
    address: '192.168.193.2',
    port: 8848,
    message: 'hello, how are you;
  })

[h2]UDPSocket.write(Object object) (1117+)

• Description

  Sends a message to the specified IP address and port. If UDPSocket.connect(Object object) is not called in advance, the usage of this method is no different from that of the UDPSocket.send(Object object) method.

  

  Even if UDPSocket.connect(Object object) is called, you still need to set the address and port parameters in this API.

• Parameters

  Parameter	Type	Mandatory	Description
  address	string	Yes	Address to which a message is sent.
  port	number	Yes	Port to which a message is sent.
  message	string/ArrayBuffer	Yes	Data to be sent.
  offset	number	No	Offset of the data to be sent. This parameter is valid only when message is of the ArrayBuffer type. The default value is 0.
  length	number	No	Length of the data to be sent. This parameter is valid only when message is of the ArrayBuffer type. The default value is message.byteLength.

• Sample code

  const udp = qg.createUDPSocket();
  udp.bind();
  udp.connect({
    address: '192.168.193.2',
    port: 8848,
  })
  udp.write({
    address: '192.168.193.2',
    port: 8848,
    message: 'hello, how are you;
  })

[h2]UDPSocket.close() (1117+)

• Description

  Closes a UDP socket instance, which is equivalent to destroying the instance. After the UDP socket instance is closed, it cannot send messages. Each time UDPSocket.send(Object object) is called, an error event is triggered, and the callback function for message events is not executed. After a UDP socket instance is created, it is strongly referenced by the native layer to prevent it from being garbage-collected. After UDPSocket.close() is called, the strong reference to the UDP socket instance is removed so that the instance complies with garbage collection.

[h2]UDPSocket.onClose(function listener) (1117+)

• Description

  Listens for closing events.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function for closing events.

[h2]UDPSocket.offClose(function listener) (1117+)

• Description

  Removes the callback function for closing events.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function passed by UDPSocket.onClose(function listener).

• Sample code

  const listener = function (res) {
    console.log(res);
  }
  
  UDPSocket.onClose(listener);
  UDPSocket.offClose(listener);    // The passed function object must be the same as that used for listening.

[h2]UDPSocket.onError(function listener) (1117+)

• Description

  Listens for error events.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function for error events.

• Returns

  An object that consists of error messages.

  Parameter	Type	Description
  code	number	Result code. For details, please refer to the result code description.
  errMsg	string	Error message.

  • Result code description

    Result Code	Description
    1	Binding error.
    2	An error occurred when listening for data packet messages.
    3	An error occurred when calling the UDPSocket.connect(Object object) method.
    4	Data sending error.
    5	Data receiving error.
    6	Incorrect TTL settings.
    7	Domain name resolution failed.

[h2]UDPSocket.offError(function listener) (1117+)

• Description

  Removes the callback function for error events.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function passed by UDPSocket.onError(function listener).

• Sample code

  const listener = function (res) {
    console.log(res);
  }
  
  UDPSocket.onError(listener);
  UDPSocket.offError(listener);    // The passed function object must be the same as that used for listening.

[h2]UDPSocket.onListening(function listener) (1117+)

• Description

  Listens for events of starting to listen for data packet messages.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Specifies the callback function for events of starting to listen for data packet messages.

[h2]UDPSocket.offListening(function listener) (1117+)

• Description

  Removes the callback function for events of starting to listen for data packet messages.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function passed by UDPSocket.onListening(function listener).

• Sample code

  const listener = function (res) {
    console.log(res);
  }
  
  UDPSocket.onListening(listener);
  UDPSocket.offListening(listener);    // The passed function object must be the same as that used for listening.

[h2]UDPSocket.onMessage(function listener) (1117+)

• Description

  Listens for message receiving events.

  • Parameters

    Parameter	Type	Mandatory	Description
    listener	function	Yes	Callback function for message receiving events.

• Returns

  An object that consists of information about received messages.

  Parameter	Type	Description
  message	ArrayBuffer	Received message. The message length must be less than 4,096 bytes.
  remoteInfo	Object	Information about the sender address. For details, please refer to parameters in remoteInfo.
  localInfo	Object	Information about the receiver address. For details, please refer to parameters in localInfo.

  • Parameters in remoteInfo

    Parameter	Type	Description
    address	string	Address of the socket that sends messages.
    family	string	Protocol family. The value can be IPv4 or IPv6.
    port	number	Port number.
    size	number	Size of a message, in bytes.

  • Parameters in localInfo

    Parameter	Type	Description
    address	string	Address of the socket that receives messages.
    family	string	Protocol family. The value can be IPv4 or IPv6.
    port	number	Port number.

[h2]UDPSocket.offMessage(function listener) (1117+)

• Description

  Removes the callback function for message receiving events.

• Parameters

  Parameter	Type	Mandatory	Description
  listener	function	Yes	Callback function passed by UDPSocket.onMessage(function listener).

• Sample code

  const listener = function (res) {
    console.log(res);
  }
  
  UDPSocket.onMessage(listener);
  UDPSocket.offMessage(listener);    // The passed function object must be the same as that used for listening.