# Network
# Making Requests
# request
Supported since Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38
request(Object object)
Uses native APIs to initiate an HTTP network request. Returns a RequestTask object after execution.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| url | string | Yes | Developer server interface address | |
| data | string/object/ArrayBuffer | No | Request parameters | |
| header | Object | No | Set request headers. Referer cannot be set in headers. content-type defaults to application/json | |
| method | string | GET | No | HTTP request method |
| dataType | string | json | No | Response data format |
| responseType | string | text | No | Response data type |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
Valid values for object.method
| Value | Description |
|---|---|
| OPTIONS | HTTP request OPTIONS |
| GET | HTTP request GET |
| HEAD | HTTP request HEAD |
| POST | HTTP request POST |
| PUT | HTTP request PUT |
| DELETE | HTTP request DELETE |
| TRACE | HTTP request TRACE |
| CONNECT | HTTP request CONNECT |
Valid values for object.dataType
| Value | Description |
|---|---|
| json | Returned data is JSON, which will be parsed with JSON.parse |
| Other | Returned content will not be parsed with JSON.parse |
Valid values for object.responseType
| Value | Description |
|---|---|
| text | Response data is text |
| arraybuffer | Response data is ArrayBuffer |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| data | string/object/ArrayBuffer | Data returned by the developer server |
| statusCode | number | HTTP status code returned by the developer server |
| header | Object | HTTP Response Header returned by the developer server |
Example code
ft.request({
url: 'test.php', // Example only, not a real interface address
data: {
x: '',
y: ''
},
header: {
'content-type': 'application/json' // Default value
},
success(res) {
console.log(res.data)
}
})
# RequestTask.abort
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.abort()
Aborts the request task.
Example code
const task = ft.request({
// some params
})
// Abort the request
task.abort()
# RequestTask.onHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.onHeadersReceived(function callback)
Listens for HTTP Response Header events, which occur earlier than the request completion event.
Parameters
function callback
Callback function for the Header Received event.
Callback function parameters
Object res
| Property | Type | Description |
|---|---|---|
| header | Object | HTTP Response Header returned by the developer server |
# RequestTask.offHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
RequestTask.offHeadersReceived(function callback)
Cancels listening for HTTP Response Header events.
Parameters
function callback
Callback function for the Header Received event.
# Download
# downloadFile
Supported since Base Library 1stance 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38
downloadFile(Object object)
Downloads file resources to local storage. The client directly initiates an HTTPS GET request and returns the local temporary path of the file.
Returns a DownloadTask after calling.
Note
Please specify a reasonable Content-Type field in the server's response header to ensure the client handles the file type correctly.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| url | string | Yes | URL of the resource to download | |
| header | Object | No | Set request headers. Referer cannot be set in headers. | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| tempFilePath | string | Temporary file path. |
| statusCode | number | HTTP status code returned by the developer server |
Example code
ft.downloadFile({
url: 'https://example.com/audio/123', // Example only, not a real resource
success(res) {
// As long as the server responds with data, the response content will be written to a file and the success callback will be triggered. Business logic needs to determine if the desired content was downloaded.
if (res.statusCode === 200) {
ft.playVoice({
filePath: res.tempFilePath
})
}
}
})
# DownloadTask.abort
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
DownloadTask.abort()
Aborts the download task.
Example code
const task = ft.request({
// some params
})
// Abort the request
task.abort()
# DownloadTask.onHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
DownloadTask.onHeadersReceived(function callback)
Listens for HTTP Response Header events, which occur earlier than the request completion event.
Parameters
function callback
Callback function for the Header Received event.
Callback function parameters
Object res
| Property | Type | Description |
|---|---|---|
| header | Object | HTTP Response Header returned by the developer server |
# DownloadTask.offHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
DownloadTask.offHeadersReceived(function callback)
Cancels listening for HTTP Response Header events.
Parameters
function callback
Callback function for the Header Received event.
# DownloadTask.onProgressUpdate
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
DownloadTask.onProgressUpdate(function callback)
Listens for download progress update events.
Parameters
function callback
Callback function for the Progress Update event.
Callback function parameters
Object res
| Property | Type | Description |
|---|---|---|
| progress | number | Download progress percentage |
| totalBytesWritten | number | Amount of data already downloaded, in Bytes |
| totalBytesExpectedToWrite | number | Total expected data length to download, in Bytes |
Example code
const task = ft.downloadFile({
// some params
})
// Listen for progress updates
task.onProgressUpdate((res) => {
this.setData({
progress: res.progress
})
})
# DownloadTask.offProgressUpdate
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
DownloadTask.offProgressUpdate(function callback)
Cancels listening for download progress updates.
Parameters
function callback
Callback function for the Progress Update event.
# Upload
# uploadFile
Supported since Base Library 1.3.9, iOS SDK 2.1.23, Android SDK 2.1.38
uploadFile(Object object)
Uploads local resources to the server. The client initiates an HTTPS POST request with content-type set to multipart/form-data.
Returns an UploadTask after calling.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| url | string | Yes | Developer server address | |
| filePath | string | Yes | Path of the file resource to upload | |
| name | string | Yes | Key corresponding to the file. The developer can retrieve the file's binary content on the server using this key. | |
| header | Object | No | Set request headers. Referer cannot be set in headers. | |
| formData | Object | No | Additional form data for the HTTP request | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
object.success callback function
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| data | string | Data returned by the developer server |
| statusCode | number | HTTP status code returned by the developer server |
Example code
ft.chooseImage({
success(res) {
const tempFilePaths = res.tempFilePaths
ft.uploadFile({
url: 'https://example.weixin.qq.com/upload', // Example only, not a real interface address
filePath: tempFilePaths[0],
name: 'file',
formData: {
user: 'test'
},
success(res) {
const data = res.data
// do something
}
})
}
})
# UploadTask.abort
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
UploadTask.abort()
Aborts the upload task.
Example code
const task = ft.request({
// some params
})
// Abort the request
task.abort()
# UploadTask.onHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
UploadTask.onHeadersReceived(function callback)
Listens for HTTP Response Header events, which occur earlier than the request completion event.
Parameters
function callback
Callback function for the Header Received event.
Callback function parameters
Object res
| Property | Type | Description |
|---|---|---|
| header | Object | HTTP Response Header returned by the developer server |
# UploadTask.offHeadersReceived
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
UploadTask.offHeadersReceived(function callback)
Cancels listening for HTTP Response Header events.
Parameters
functioncallback
Callback function for the Header Received event.
# UploadTask.onProgressUpdate
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
UploadTask.onProgressUpdate(function callback)
Listens for upload progress update events.
Parameters
function callback
Callback function for the Progress Update event.
Callback function parameters
Object res
| Property | Type | Description |
|---|---|---|
| progress | number | Upload progress percentage |
| totalBytesSent | number | Amount of data already uploaded, in Bytes |
| totalBytesExpectedToSend | number | Total expected data length to upload, in Bytes |
Example code
const task = ft.uploadFile({
// some params
})
// Listen for progress updates
task.onProgressUpdate((res) => {
this.setData({
progress: res.progress
})
})
# UploadTask.offProgressUpdate
Supported since Base Library 2.4.2, iOS SDK 2.13.59, Android SDK 2.13.34
UploadTask.offProgressUpdate(function callback)
Cancels listening for upload progress updates.
Parameters
function callbackCallback function for the Progress Update event.
# Websocket
# sendSocketMessage
ft.sendSocketMessage(Object object)
Sends data through a WebSocket connection. Requires calling ft.connectSocket first and can only send after the ft.onSocketOpen callback.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| data | string/ArrayBuffer | Yes | Content to send | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
Example code
let socketOpen = false
let socketMsgQueue = []
ft.connectSocket({
url: 'test.php'
})
ft.onSocketOpen(function(res) {
socketOpen = true
for (let i = 0; i < socketMsgQueue.length; i++){
sendSocketMessage(socketMsgQueue[i])
}
socketMsgQueue = []
})
function sendSocketMessage(msg) {
if (socketOpen) {
ft.sendSocketMessage({
data:msg
})
} else {
socketMsgQueue.push(msg)
}
}
# onSocketOpen
ft.onSocketOpen(function callback)
Listens for WebSocket connection open events.
Parameters
function callback
Callback function for the WebSocket connection open event.
Parameters
| Property | Type | Description |
|---|---|---|
| header | object | HTTP response header upon successful connection |
# onSocketMessage
ft.onSocketMessage(function callback)
Listens for WebSocket message reception events from the server.
Parameters
function callback
Callback function for the WebSocket message reception event.
Parameters
Object res
| Property | Type | Description |
|---|---|---|
| data | string/ArrayBuffer | Message returned by the server |
# onSocketError
ft.onSocketError(function callback)
Listens for WebSocket error events.
Parameters
function callback
Callback function for the WebSocket error event.
Parameters
# Object res
| Property | Type | Description |
|---|---|---|
| errMsg | string | Error message |
# onSocketClose
ft.onSocketClose(function callback)
Listens for WebSocket connection close events.
Parameters
function callback
Callback function for the WebSocket connection close event.
Parameters
# Object res
| Property | Type | Description |
|---|---|---|
| code | number | A numeric value indicating the connection close status code, representing the reason for closure. |
| reason | string | A human-readable string indicating the reason for closure. This string must be UTF-8 text (not characters) no longer than 123 bytes. |
# connectSocket
SocketTask ft.connectSocket(Object object)
Creates a WebSocket connection. Please read the relevant instructions before use.
Parameters
Object object
| Property | Type | Default Value | Required | Description | Minimum Version |
|---|---|---|---|---|---|
| url | string | Yes | Developer server wss interface address | ||
| header | Object | No | HTTP Header. Referer cannot be set in Header. | ||
| protocols | Array.<string> | No | Sub-protocol array | 1.4.0 | |
| tcpNoDelay | boolean | false | 否 | TCP_NODELAY setting when establishing the TCP connection | 2.4.0 |
| perMessageDeflate | boolean | false | 否 | Whether to enable compression extension | 2.8.0 |
| timeout | number | 否 | Timeout duration in milliseconds | 2.10.0 | |
| success | function | No | Callback function for successful API call | ||
| fail | function | No | Callback function for failed API call | ||
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
Return Value
SocketTask
WebSocket task.
Example code
ft.connectSocket({
url: 'wss://example.qq.com',
header:{
'content-type': 'application/json'
},
protocols: ['protocol1']
})
# closeSocket
ft.closeSocket(Object object)
Closes the WebSocket connection.
Parameters
Object object
| Property | Type | Default Value | Required | Description |
|---|---|---|---|---|
| code | number | 1000 (indicating normal closure) | No | A numeric value indicating the connection close status code, representing the reason for closure. |
| reason | string | No | A human-readable string indicating the reason for closure. This string must be UTF-8 text (not characters) no longer than 123 bytes. | |
| success | function | No | Callback function for successful API call | |
| fail | function | No | Callback function for failed API call | |
| complete | function | No | Callback function for API call completion (executes regardless of success or failure) |
Example code
ft.connectSocket({
url: 'test.php'
})
// Note the timing issue here.
// If ft.connectSocket hasn't called back ft.onSocketOpen yet, and ft.closeSocket is called first, then the WebSocket cannot be closed.
// ft.closeSocket must be called while the WebSocket is open to close it.
ft.onSocketOpen(function() {
ft.closeSocket()
})
ft.onSocketClose(function(res) {
console.log('WebSocket closed!')
})
# SocketTask
WebSocket task, which can be created and returned by the ft.connectSocket() interface.
Methods
SocketTask.send(Object object)
Sends data through the WebSocket connection.SocketTask.close(Object object)
Closes the WebSocket connection.SocketTask.onOpen(function callback)
Listens for WebSocket connection open events.SocketTask.onClose(function callback)
Listens for WebSocket connection close events.SocketTask.onError(function callback)
Listens for WebSocket error events.SocketTask.onMessage(function callback)
Listens for WebSocket message reception events from the server.
# UDP Communication
# ft.createUDPSocket
ft.createUDPSocket() Creates a UDP Socket instance.
Return Value
UDPSocket
A UDP Socket instance.
# UDPSocket
A UDP Socket instance, using IPv4 protocol by default.
Methods
number UDPSocket.bind(number port)
Binds to a system-randomly assigned available port, or binds to a specified port number.
UDPSocket.setTTL(number ttl)
Sets the IP_TTL socket option, used to set the maximum number of hops allowed for an IP datagram transmission.
UDPSocket.send(Object object)
Sends a message to the specified IP and port.
UDPSocket.connect(Object object)
Pre-connects to the specified IP and port, needs to be used together with the write method.
UDPSocket.write()
Usage is the same as the send method. If connect was not called beforehand, it is identical to send (Note: even if connect is called, the address and port parameters still need to be provided in this interface).
UDPSocket.close()
Closes the UDP Socket instance, effectively destroying it. After closing, the UDP Socket instance can no longer send messages. Each call to UDPSocket.send will trigger an error event, and the message event callback function will also no longer execute. After the UDPSocket instance is created, it is strongly referenced by Native to prevent GC. After UDPSocket.close(), the strong reference is removed, allowing the UDPSocket instance to be subject to GC.
UDPSocket.onClose(function callback)
Listens for the close event.
UDPSocket.offClose(function callback)
Cancels listening for the close event.
UDPSocket.onError(function callback)
Listens for the error event.
UDPSocket.offError(function callback)
Cancels listening for the error event.
UDPSocket.onListening(function callback)
Listens for the event indicating start of listening for datagram messages.
UDPSocket.offListening(function callback)
Cancels listening for the event indicating start of listening for datagram messages.
UDPSocket.onMessage(function callback)
Listens for the message reception event.
UDPSocket.offMessage(function callback)
Cancels listening for the message reception event.
Errors
| Error Code | Error Message | Description |
|---|---|---|
| -1 | System error | |
| -2 | Socket interface error | |
| -3 | Send failed, no interface permission | |
| 1 | Send failed, parameter error, invalid address | |
| 2 | Send failed, parameter error, invalid port |