rcp (Data Requests)

Modules to Import

import { rcp } from '@kit.RemoteCommunicationKit';

createSession

createSession(sessionConfiguration?: SessionConfiguration): Session

Creates an HTTP session. This is the main method for starting an HTTP interaction. You can use this API and SessionConfiguration together to create and configure a session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

const session = rcp.createSession();

Session

Represents a communication session that can be used to initiate HTTP requests. It supports various HTTP methods, such as FETCH, GET, POST, PUT, HEAD, DELETE, CANCEL and CLOSE.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Properties

fetch

fetch(request: Request): Promise<Response>

Sends an HTTP request and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
let req = new rcp.Request('http://example.com/fetch', 'POST');
session.fetch(req).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

fetchForSendable

fetchForSendable(request: Request): Promise<ResponseSendable>

Sends an HTTP request and obtains an HTTP response from the server. The response message supports Sendable. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.0.0(20)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { ArkTSUtils, collections, taskpool, util } from '@kit.ArkTS';

@Concurrent
async function taskFunc(sendableResponse: rcp.ResponseSendable) {
  console.info(`sendableResponse: ${ArkTSUtils.ASON.stringify(sendableResponse)}`);
  // Print the body data of the Sendable type.
  if (ArkTSUtils.isSendable(sendableResponse.body) && sendableResponse.body != undefined) {
    const decoder = util.TextDecoder.create('utf-8');
    let arr: collections.Uint8Array = new collections.Uint8Array(sendableResponse.body);
    let str = decoder.decodeToString(arr as Object as Uint8Array).trim();
    console.info(`body:${ArkTSUtils.ASON.stringify(str)}`);
  }
}

async function test() {
  try {
    const session = rcp.createSession();
    let request = new rcp.Request('https://www.example.com'); // Replace the URL with the actual one.
    let sendableResponse = await session.fetchForSendable(request);
    let isSendable = ArkTSUtils.isSendable(sendableResponse);
    if (isSendable) {
      console.info(`Succeeded in getting the response, the response is sendable`);
    } else {
      console.info(`Succeeded in getting the response, the response is not sendable`);
    }
    let task: taskpool.Task = new taskpool.Task(taskFunc, sendableResponse);
    await taskpool.execute(task);
  } catch (err) {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  }
}

get

get(url: URLOrString, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP GET request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
session.get('http://example.com/get').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

post

post(url: URLOrString, content?: RequestContent, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP POST request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
session.post('http://example.com/post', 'data to send').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

put

put(url: URLOrString, content?: RequestContent, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP PUT request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
session.put('http://example.com/put', 'data to send').then((response) => {
  console.info(`Succeeded in getting the response ${response.toString()}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

downloadToFile

downloadToFile(url: URLOrString, downloadTo: DownloadToFile): Promise<Response>

Sends an HTTP DOWNLOADTOFILE request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let downloadToFile: rcp.DownloadToFile = {
  kind: 'folder',
  path: '/path/dir' // Set the path based on your service needs.
} as rcp.DownloadToFile
const session = rcp.createSession();
session.downloadToFile('http://www.example.com', downloadToFile).then((response) => {
  console.info(`Succeeded in getting the response ${response.toString()}`);
}).catch((err: BusinessError) => {
  console.error(`DownloadToFile failed, the error code is ${err.code}, error data is ${err.data}`);
});

uploadFromFile

uploadFromFile(url: URLOrString, uploadFrom: UploadFromFile): Promise<Response>

Sends an HTTP UPLOADFROMFILE request carrying default HTTP parameters to complete file upload and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let fileDir = '/path/dir/'; // Define the path based on the service requirements.
let uploadFromFile: rcp.UploadFromFile = {
  fileOrPath: fileDir
};
const session = rcp.createSession();
session.uploadFromFile('http://example.com/head', uploadFromFile).then((response) => {
  console.info(`Succeeded in getting the response ${response.toString()}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

downloadToStream

downloadToStream(url: URLOrString, downloadTo: DownloadToStream): Promise<Response>

Sends an HTTP DOWNLOADTOSTREAM request carrying default HTTP parameters to request downloading data in stream mode from the server and obtains an HTTP response. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

const streamData: rcp.WriteStream = {
  write(buffer: ArrayBuffer): Promise<void | number> {
    return Promise.resolve(buffer.byteLength)
  }
};

let downloadToStream: rcp.DownloadToStream = {
  kind: 'stream',
  stream: streamData
}
const session = rcp.createSession();
session.downloadToStream('http://example.com/head', downloadToStream).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

uploadFromStream

uploadFromStream(url: URLOrString, uploadFrom: UploadFromStream): Promise<Response>

Sends an HTTP UPLOADFROMSTREAM request carrying default HTTP parameters to upload data in stream mode to the server and obtains an HTTP response. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let uploadFromStream: rcp.UploadFromStream = {
  stream: object // Define an object of the Stream, ReadStream, or SyncReadStream type.
}
const session = rcp.createSession();
session.uploadFromStream('http://example.com/head', uploadFromStream).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

head

head(url: URLOrString): Promise<Response>

Sends an HTTP HEAD request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
session.head('http://example.com/head').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

delete

delete(url: URLOrString): Promise<Response>

Sends an HTTP DELETE request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
session.delete('http://example.com/delete').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

cancel

cancel(requestToCancel?: Request | Request[]): void

Cancels a specified request or all ongoing requests in a session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
let req = new rcp.Request('http://example.com/fetch', 'GET');
session.fetch(req).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
  session.cancel(req);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

close

close(): void

Closes a session. This API frees up resources related to this session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const session = rcp.createSession();
let req = new rcp.Request('http://example.com/fetch', 'GET');
session.fetch(req).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
  session.close();
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
  session.close();
});

getDefaultSession

getDefaultSession(): DefaultSession

Obtains the default HTTP session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Returns:

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();

DefaultSession

Provides a default session for sending HTTP requests. If session customization is not required, you can simply use DefaultSession to initiate network requests.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

fetch

fetch(request: Request): Promise<Response>

Sends an HTTP request and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
let req = new rcp.Request('http://example.com/fetch', 'POST');
defaultSession.fetch(req).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

fetchForSendable

fetchForSendable(request: Request): Promise<ResponseSendable>

Sends an HTTP request and obtains an HTTP response from the server. The response message supports Sendable. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { ArkTSUtils, collections, taskpool, util } from '@kit.ArkTS';

@Concurrent
async function taskFunc(sendableResponse: rcp.ResponseSendable) {
  console.info(`sendableResponse: ${ArkTSUtils.ASON.stringify(sendableResponse)}`);
  // Print the body data of the Sendable type.
  if (ArkTSUtils.isSendable(sendableResponse.body) && sendableResponse.body != undefined) {
    const decoder = util.TextDecoder.create('utf-8');
    let arr: collections.Uint8Array = new collections.Uint8Array(sendableResponse.body);
    let str = decoder.decodeToString(arr as Object as Uint8Array).trim();
    console.info(`body:${ArkTSUtils.ASON.stringify(str)}`);
  }
}

async function test() {
  try {
    const defaultSession = rcp.getDefaultSession();
    let request = new rcp.Request('https://www.example.com'); // Replace the URL with the actual one.
    let sendableResponse = await defaultSession.fetchForSendable(request);
    let isSendable = ArkTSUtils.isSendable(sendableResponse);
    if (isSendable) {
      console.info(`Succeeded in getting the response, the response is sendable`);
    } else {
      console.info(`Succeeded in getting the response, the response is not sendable`);
    }
    let task: taskpool.Task = new taskpool.Task(taskFunc, sendableResponse);
    await taskpool.execute(task);
  } catch (err) {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  }
}

get

get(url: URLOrString, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP GET request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
defaultSession.get('http://example.com/get').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

post

post(url: URLOrString, content?: RequestContent, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP POST request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
defaultSession.post('http://example.com/post', 'data to send').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

put

put(url: URLOrString, content?: RequestContent, destination?: ResponseBodyDestination): Promise<Response>

Sends an HTTP PUT request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
defaultSession.put('http://example.com/put', 'data to send').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

downloadToFile

downloadToFile(url: URLOrString, downloadTo: DownloadToFile): Promise<Response>

Sends an HTTP DOWNLOADTOFILE request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let downloadToFile: rcp.DownloadToFile = {
  kind: 'folder',
  path: '/path/dir' // Set the path based on your service needs.
} as rcp.DownloadToFile
const defaultSession = rcp.getDefaultSession();
defaultSession.downloadToFile('http://www.example.com', downloadToFile).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`DownloadToFile failed, the error code is ${err.code}, error data is ${err.data}`);
});

uploadFromFile

uploadFromFile(url: URLOrString, uploadFrom: UploadFromFile): Promise<Response>

Sends an HTTP UPLOADFROMFILE request carrying default HTTP parameters to complete file upload and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let fileDir = '/path/dir/'; // Define the path based on the service requirements.
let uploadFromFile: rcp.UploadFromFile = {
  fileOrPath: fileDir
};
const defaultSession = rcp.getDefaultSession();
defaultSession.uploadFromFile('http://example.com/head', uploadFromFile).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

downloadToStream

downloadToStream(url: URLOrString, downloadTo: DownloadToStream): Promise<Response>

Sends an HTTP DOWNLOADTOSTREAM request carrying default HTTP parameters to request downloading data in stream mode from the server and obtains an HTTP response. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit'

const streamData: rcp.WriteStream = {
  write(buffer: ArrayBuffer): Promise<void | number> {
    return Promise.resolve(buffer.byteLength)
  }
};

let downloadToStream: rcp.DownloadToStream = {
  kind: 'stream',
  stream: streamData
}
const defaultSession = rcp.getDefaultSession();
defaultSession.downloadToStream('http://example.com/head', downloadToStream).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

uploadFromStream

uploadFromStream(url: URLOrString, uploadFrom: UploadFromStream): Promise<Response>

Sends an HTTP UPLOADFROMSTREAM request carrying default HTTP parameters to upload data in stream mode to the server and obtains an HTTP response. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

let uploadFromStream: rcp.UploadFromStream = {
  stream: object // Define an object of the Stream, ReadStream, or SyncReadStream type.
}
const defaultSession = rcp.getDefaultSession();
defaultSession.uploadFromStream('http://example.com/head', uploadFromStream).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

head

head(url: URLOrString): Promise<Response>

Sends an HTTP HEAD request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
defaultSession.head('http://example.com/head').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

delete

delete(url: URLOrString): Promise<Response>

Sends an HTTP DELETE request carrying default HTTP parameters and obtains an HTTP response from the server. This API uses a promise to return the result.

Required permissions: ohos.permission.INTERNET (If the cellular option of PathPreference is used, the ohos.permission.GET_NETWORK_INFO permission is also required.)

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
defaultSession.delete('http://example.com/delete').then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

cancel

cancel(requestToCancel?: Request | Request[]): void

Cancels a specified request or all ongoing requests in a session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { BusinessError } from '@kit.BasicServicesKit';
import { rcp } from '@kit.RemoteCommunicationKit';

const defaultSession = rcp.getDefaultSession();
let req = new rcp.Request('http://example.com/fetch', 'GET');
defaultSession.fetch(req).then((response) => {
  console.info(`Succeeded in getting the response ${response}`);
  defaultSession.cancel(req);
}).catch((err: BusinessError) => {
  console.error(`err: error code is ${err.code}, error data is ${err.data}`);
});

RequestHandler

Provides the interceptor handler.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

handle

handle(context: RequestContext): Promise<Response>

Entry point function of the request handler. Each interceptor calls the handle method of the RequestHandler at the next level to trigger the intercept function of the next-level interceptor, which ultimately triggers a request to the server. This API uses a promise to return the result.

For example, the interceptor [A, B, C, D] is constructed as A {handler->B{handler->C{handler-D{handler->system capability}}}}.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Example:

For details, please refer to the code example of Interceptor.

RequestContext

Defines the interceptor request context.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Interceptor

Defines an interceptor.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

intercept

intercept(context: RequestContext, next: RequestHandler): Promise<Response>

Interceptor, which is used to modify requests, modify responses, or directly return responses. It uses a promise to return the result asynchronously.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

class ResponseCache {
  private readonly cache: Record<string, rcp.Response> = {};

  getResponse(url: string): rcp.Response {
    return this.cache[url];
  }

  setResponse(url: string, response: rcp.Response): void {
    this.cache[url] = response;
  }
}

class ResponseCachingInterceptor implements rcp.Interceptor {
  private readonly cache: ResponseCache;

  constructor(cache: ResponseCache) {
    this.cache = cache;
  }

  async intercept(context: rcp.RequestContext, next: rcp.RequestHandler): Promise<rcp.Response> {
    const url = context.request.url.href;
    const responseFromCache = this.cache.getResponse(url);
    if (responseFromCache) {
      return Promise.resolve(responseFromCache);
    }
    const promise = next.handle(context);
    promise.then((resp) => {
      resp.statusCode;
      cache.setResponse(url, resp);
    });
    return promise;
  }
}

const cache = new ResponseCache();

function testInterceptor() {
  const session = rcp.createSession({
    interceptors: [new ResponseCachingInterceptor(cache)]
  });

  session.get('https://www.example.com').then((response: rcp.Response) => {
    console.info(`Succeeded in getting the response. The statusCode of the response is ${response.statusCode}`);
  }).catch((err: BusinessError) => {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  });

  let request = new rcp.Request('https://www.example.com', 'GET');
  session.fetch(request).then((response: rcp.Response) => {
    console.info(`Succeeded in fetching the response. The statusCode of the response is ${response.statusCode}`);
  }).catch((err: BusinessError) => {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  });
}

SessionConfiguration

Defines the configuration parameters of a session, providing detailed control over various aspects of the HTTP session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

let cookieRepository = rcp.CookieRepository.create();
const sessionConfig: rcp.SessionConfiguration = {
  requestConfiguration: {
    transfer: {
      autoRedirect: true,
      timeout: {
        connectMs: 5000,
        transferMs: 10000
      }
    },
    tracing: {
      verbose: true
    }
  },
  baseAddress: 'http://api.example.com',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  cookies: {
    'user': 'john_doe',
    'session_id': 'abc123'
  },
  sessionListener: {
    onCanceled: () => console.info('Session was cancelled'),
    onClosed: () => console.info('Session was closed')
  },
  cookieRepository: cookieRepository,
  // ...
};

const session = rcp.createSession(sessionConfig);

Parameter example of interceptors:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

class ResponseCache {
  private readonly cache: Record<string, rcp.Response> = {};

  getResponse(url: string): rcp.Response {
    return this.cache[url];
  }

  setResponse(url: string, response: rcp.Response): void {
    this.cache[url] = response;
  }
}

class ResponseCachingInterceptor implements rcp.Interceptor {
  private readonly cache: ResponseCache;

  constructor(cache: ResponseCache) {
    this.cache = cache;
  }

  async intercept(context: rcp.RequestContext, next: rcp.RequestHandler): Promise<rcp.Response> {
    const url = context.request.url.href;
    const responseFromCache = this.cache.getResponse(url);
    if (responseFromCache) {
      return Promise.resolve(responseFromCache);
    }
    const promise = next.handle(context);
    promise.then((resp) => {
      this.cache.setResponse(url, resp);
    });
    return promise;
  }
}

const cache = new ResponseCache();

function testInterceptor() {
  const session = rcp.createSession({
    interceptors: [new ResponseCachingInterceptor(cache)]
  });

  session.get('https://www.example.com').then((response: rcp.Response) => {
    console.info(`Succeeded in getting the response. The statusCode of the response is ${response.statusCode}`);
  }).catch((err: BusinessError) => {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  });

  let request = new rcp.Request('https://www.example.com', 'GET');
  session.fetch(request).then((response: rcp.Response) => {
    console.info(`Succeeded in fetching the response. The statusCode of the response is ${response.statusCode}`);
  }).catch((err: BusinessError) => {
    console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
  });
}

Configuration

Defines parameters that you can use to define HTTP requests in a session, including transmission, tracing, proxy, DNS, and security settings.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

const cache: rcp.ResponseCache = new rcp.ResponseCache({
  persistent: {
    kind: 'file-system',
    pathToFolder: '/path/dir/' // Specify the cache path based on your service needs.
  }
});
const requestConfig: rcp.Configuration = {
  transfer: {
    autoRedirect: true,
    timeout: {
      connectMs: 5000,
      transferMs: 10000
    },
    assumesHTTP3Capable: true,
    pathPreference: 'cellular'
  },
  tracing: {
    verbose: true
  },
  proxy: 'system',
  dns: {
    dnsRules: [
      { host: 'https://example.com', port: 443, ipAddresses: ['192.168.1.1', '192.168.1.2'] }
    ]
  },

  security: {
    certificate: {
      content: '-----BEGIN CERTIFICATE-----\n...',
      type: 'PEM',
      key: '/path/dir/', // Change the key based on your service needs.
      keyPassword: 'your-password'
    },
    serverAuthentication: {
      credential: {
        username: 'your-username',
        password: 'your-password'
      },
      authenticationType: 'basic'
    }
  },
  cache: cache
};

// Create a session using the configuration.
const session = rcp.createSession({ requestConfiguration: requestConfig });

ConnectionConfiguration

Sets the total number of concurrent TCP connections and the maximum number of TCP connections allowed to a single host in a session.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

const connectionConfig: rcp.ConnectionConfiguration = {
  maxConnectionsPerHost: 6,
  maxTotalConnections: 64
}
const session = rcp.createSession({ connectionConfiguration: connectionConfig });

TcpConfiguration

Enables settings of TCP options.

When any of the keepIdleSec, keepCnt, and keepIntervalSec parameters is set, the client sends a probe packet proactively. Parameters that are not set will use their default value. If the server does not respond to the probe packet within the specified duration in seconds (keepIdleSec + (keepCnt + 1) x keepIntervalSec), the TCP connection will be terminated.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.0.0(20)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

const transferConfig: rcp.TransferConfiguration = {
  tcp: {
    keepIdleSec: 20,
    userTimeoutMs: 3000,
    keepCnt: 6,
    keepIntervalSec: 30,
  }
};

// Create a session using the configuration.
const session = rcp.createSession({
  requestConfiguration: {
    transfer: transferConfig
  }
});

// Create a request using the configuration.
const request = new rcp.Request('https://example.com');
request.configuration = {
  transfer: transferConfig
};

CookieRepository

Cookie repository, which can automatically captures cookies from HTTP responses and includes cookies in requests, while also supporting manual cookie management. The cookie repository persists to local storage every 30 seconds. Alternatively, you can trigger an immediate local save by calling setCookies. Sessions that use the cookie repository actually process requests through DefaultSession.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

create

static create(identifier?: string): CookieRepository

Creates a cookie repository.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

try {
  rcp.CookieRepository.create('myRepo');
} catch (err) {
  console.error(`Error: error code is ${err.code}, error data is ${err.data}`);
}

setCookies

setCookies(cookies: ResponseCookie | ResponseCookie[]): Promise<void>

Adds or modifies cookies, and persists existing cookies in the cookie repository to local storage. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let cookieRepository = rcp.CookieRepository.create('myRepo');
let cookie: rcp.ResponseCookie = {
   name:'session_1',
   value:'10001',
   domain:'www.example.com', // Set the domain name based on your needs.
   maxAge: 60,
   isSecure: true
}
cookieRepository.setCookies(cookie).then(() => {
  console.info('Succeeded in setting cookies.');
}).catch((err: BusinessError) => {
  console.error(`setCookies error, error code is ${err.code}, error data is ${err.data}`);
})

getAllCookies

getAllCookies(): Promise<ResponseCookie[]>

Queries all cookies in the cookie repository. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let cookieRepository = rcp.CookieRepository.create('myRepo');
cookieRepository.getAllCookies().then((cookies) => {
  console.info(`Succeeded in getting all cookies, cookies num: ${cookies.length}`);
}).catch((err: BusinessError) => {
  console.error(`getAllCookies error, error code is ${err.code}, error data is ${err.data}`);
})

getCookiesByUrl

getCookiesByUrl(url: URL): Promise<ResponseCookie[]>

Obtains cookies from the cookie repository based on the passed URL. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { url } from '@kit.ArkTS';

let cookieRepository = rcp.CookieRepository.create('myRepo');
cookieRepository.getCookiesByUrl(url.URL.parseURL('https://www.example.com')).then((cookies) => {
  console.info(`Succeeded in getting cookies by URL, cookies num: ${cookies.length}`);
}).catch((err: BusinessError) => {
  console.error(`getCookiesByUrl error, error code is ${err.code}, error data is ${err.data}`);
})

deleteCookies

deleteCookies(cookies?: ResponseCookie | ResponseCookie[]): Promise<void>

Deletes specified cookies. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';

let cookieRepository = rcp.CookieRepository.create('myRepo');
let cookie: rcp.ResponseCookie = {
   name:'session_1',
   value:'10001',
   domain:'www.example.com', // Set the domain name based on your needs.
   maxAge: 60,
   isSecure: true
}
cookieRepository.deleteCookies(cookie).then(() => {
  console.info('Succeeded in deleting cookies.');
}).catch((err: BusinessError) => {
  console.error(`deleteCookies error, error code is ${err.code}, error data is ${err.data}`);
})

deleteCookiesByUrl

deleteCookiesByUrl(url: URL): Promise<void>

Deletes cookies from the cookie repository based on the passed URL. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

Example:

import { rcp } from '@kit.RemoteCommunicationKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { url } from '@kit.ArkTS';

let cookieRepository = rcp.CookieRepository.create('myRepo');
cookieRepository.deleteCookiesByUrl(url.URL.parseURL('https://www.example.com')).then(() => {
  console.info('Succeeded in deleting cookies by URL.');
}).catch((err: BusinessError) => {
  console.error(`deleteCookiesByUrl error, error code is ${err.code}, error data is ${err.data}`);
})

identifier

get identifier(): string

Obtains the cookie repository ID.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Returns:

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

let cookieRepository = rcp.CookieRepository.create('myRepo');
let identifier = cookieRepository.identifier;
console.info(`identifier is: ${identifier}`);

SessionPathPreference

type SessionPathPreference = 'auto' | 'cellular-if-could' | 'mptcp'

Session path preferences.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 26.0.0

TransferConfiguration

Defines data transmission settings for HTTP requests in a session, including automatic redirection and timeout settings.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

const transferConfig: rcp.TransferConfiguration = {
  autoRedirect: true,
  timeout: {
    connectMs: 5000,
    transferMs: 10000
  },
  assumesHTTP3Capable: true,
  pathPreference: 'cellular',
  connectionReusePolicy: 'balanced',
  httpVersionSelectCallback: (url: rcp.URL): rcp.HttpVersion => {
    return '2';
  },
};

// Create a session using the configuration.
const session = rcp.createSession({ requestConfiguration: { transfer: transferConfig } });

TracingConfiguration

Defines tracing settings for HTTP requests in a session, so you can collect information that can be used for data stream tracing, debugging, and performance analysis.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

// Define a custom response handler.
const customHttpEventsHandler: rcp.HttpEventsHandler = {
  onDataReceive: (incomingData: ArrayBuffer) => {
    // Custom logic for processing incoming data.
    console.info(`Received data length: ${incomingData.byteLength}`);
    return incomingData.byteLength;
  },
  onUploadProgress: (totalSize: number, transferredSize: number) => {
    // Custom logic for processing the upload progress.
    console.info(`Upload progress: ${transferredSize} of ${totalSize}`);
  },
  onDownloadProgress: (totalSize: number, transferredSize: number) => {
    // Custom logic for processing the download progress.
    console.info(`Download progress: ${transferredSize} of ${totalSize}`);
  },
  onHeaderReceive: (headers: rcp.ResponseHeaders) => {
    // Custom logic for processing response headers.
    console.info(`Received headers: ${JSON.stringify(headers)}`);
  },
  onDataEnd: () => {
    // Custom logic for processing the completion of data transmission.
    console.info('Data transfer complete');
  },
  onCanceled: () => {
    // Custom logic for processing the cancel operation.
    console.info('Request/response canceled');
  },
  onStatusCodeReceive: (statusCode: number, request?: rcp.Request) => {
    // Custom logic for processing the status code.
    console.info(`Received statusCode: ${statusCode}`);
  }
};

// Configure tracing settings.
const tracingConfig: rcp.TracingConfiguration = {
  verbose: true,
  infoToCollect: {
    textual: true,
    incomingHeader: true,
    outgoingHeader: true,
    incomingData: true,
    outgoingData: true,
    incomingSslData: true,
    outgoingSslData: true
  },
  collectTimeInfo: true,
  httpEventsHandler: customHttpEventsHandler
};

// Create a session using the configuration.
const session = rcp.createSession({requestConfiguration: {tracing: tracingConfig}});
console.info(`session id: ${session.id}`);

ProxyConfiguration

type ProxyConfiguration = 'system' | 'no-proxy' | WebProxy

Defines proxy settings for HTTP requests in a session, so you can flexibly choose between the options of system proxy, custom proxy, and no proxy.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

// Configure the system proxy (default).
const systemProxyConfig = 'system';

// Configure the custom proxy.
const customProxyConfig: rcp.WebProxy = {
  url: 'http://custom-proxy.example.com',
  createTunnel: 'always',
  exclusions: ['http://exclude.example.com'],
  security: {
    certificate: {
      content: '-----BEGIN CERTIFICATE-----\n...',
      type: 'PEM',
      key: '-----BEGIN PRIVATE KEY-----\n...', // Set the key based on your service needs.
      keyPassword: 'your-password'
    },
    serverAuthentication: {
      credential: {
        username: 'proxy-username',
        password: 'proxy-password'
      },
      authenticationType: 'basic'
    }
  }
};

// Configure the non-proxy mode.
const noProxyConfig = 'no-proxy';

// Use the proxy configuration during session creation.
const sessionWithSystemProxy = rcp.createSession({ requestConfiguration: { proxy: systemProxyConfig } });
console.info(`sessionWithSystemProxy id: ${sessionWithSystemProxy.id}`);

const sessionWithCustomProxy = rcp.createSession({ requestConfiguration: { proxy: customProxyConfig } });
console.info(`sessionWithCustomProxy id: ${sessionWithCustomProxy.id}`);

const sessionWithNoProxy = rcp.createSession({ requestConfiguration: { proxy: noProxyConfig } });
console.info(`sessionWithNoProxy id: ${sessionWithNoProxy.id}`);

DnsConfiguration

Defines DNS settings for HTTP requests in a session. You can configure DNS rules flexibly, including customizing the DNS server or static DNS rules.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

// Configure a custom DNS server. The following IP address is for reference only.
const customDnsServers: rcp.DnsServers = [
  { ip: '192.168.1.1' },
  { ip: '192.168.1.2', port: 53 }
];

// Configure a static DNS rule. The following IP address is for reference only.
const staticDnsRules: rcp.StaticDnsRules = [
  { host: 'example.com', port: 80, ipAddresses: ['192.168.1.1', '192.168.1.2'] },
  { host: 'sub.example.com', port: 443, ipAddresses: ['192.168.2.1'] }
];

// Configure DNS over HTTPS.
const dohConfig: rcp.DnsOverHttpsConfiguration = {
  url: 'https://dns.example.com/dns-query',
  skipCertificatesValidation: true
};

// Use the DNS configuration during session creation.
const sessionWithCustomDns = rcp.createSession({ requestConfiguration: { dns: { dnsRules: customDnsServers } } });
const sessionWithStaticDns = rcp.createSession({
  requestConfiguration: {
    dns: {
      // For example, '192.168.1.2' is valid for example.com.
      // For sub.example.com, '192.168.2.1' is valid.
      dnsRules: staticDnsRules,
    }
  }
});
const sessionWithDoh = rcp.createSession({ requestConfiguration: { dns: { dnsOverHttps: dohConfig } } });

// If DNS rules are set during session creation, enable happyEyeballOnDnsRule.
const sessionWithStaticDnsRulesAndHappyEyeball = rcp.createSession({
  requestConfiguration: {
    dns: {
      dnsRules: staticDnsRules, // Set DNS rules here.
      happyEyeballOnDnsRule: true, // Enable happyEyeballOnDnsRule here.
    }
  }
});

// Enable happyEyeballOnDnsRule in the request configuration when setting DNS rules.
const request = new rcp.Request('https://example.com');
request.configuration = {
  dns: {
    dnsRules: staticDnsRules, // Set DNS rules here.
    happyEyeballOnDnsRule: true, // Enable happyEyeballOnDnsRule here.
  }
};

DnsOverHttpsConfiguration

Defines DNS over HTTPS settings, allowing for secure DNS resolution via HTTPS endpoints.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

// Configure DNS over HTTPS settings.
const dohConfig: rcp.DnsOverHttpsConfiguration = {
  url: 'https://dns.example.com/dns-query',
  skipCertificatesValidation: true
};

// Use the DNS over HTTPS settings during session creation.
const sessionWithDoh = rcp.createSession({ requestConfiguration: { dns: { dnsOverHttps: dohConfig } } });

SecurityConfiguration

Defines security-related settings for a session, including certificate and server identity verification settings.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

// Configure security settings.
const securityConfig: rcp.SecurityConfiguration = {
  remoteValidation: 'system',
  certificate: {
    content: '-----BEGIN CERTIFICATE-----\n...',
    type: 'PEM',
    key: '-----BEGIN PRIVATE KEY-----\n...', // Set the key based on your service needs.
    keyPassword: 'your-password'
  },
  serverAuthentication: {
    credential: {
      username: 'exampleUser',
      password: 'examplePassword'
    },
    authenticationType: 'basic'
  },
  tlsOptions: {
    tlsVersion: 'TlsV1.3',
  },
  certificateDecompress: 'zlib',
};

// Use the security settings during session creation.
const sessionWithSecurityConfig = rcp.createSession({ requestConfiguration: { security: securityConfig } });

CertificateAuthority

CA used to verify the identity of a remote server.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

ClientCertificate

Client certificate.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

ServerAuthentication

Defines HTTP server identity verification information.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

TlsVersionRangeOptions

Sets the available TLS version range. You can define the minimum and maximum bounds of supported TLS versions for security purposes, and specify the list of cipher suites available within the range. If the minimum version is later than the maximum version, the error 401 will be reported when a request is initiated.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.0.0(20)

OnAuthenticationChallenge

type OnAuthenticationChallenge = (info: AuthenticationChallengeInfo[], response: Response, challengeCount: number) => ServerAuthentication | null

Authentication challenge callback function. You can use this callback function to process the authentication challenge. This callback function is called when the HTTP response status code is 401.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Parameters:

Returns:

SecurityLayerType

type SecurityLayerType = 'ssl-tls' | 'tlcp'

Security-layer protocol type.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 26.0.0

CertificateDecompress

type CertificateDecompress = 'zlib' | 'brotli'

Certificate decompression algorithm. For details, please refer to RFC 8879.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 26.0.0

AuthenticationChallengeInfo

type AuthenticationChallengeInfo = Record<string, string>

Defines authentication challenge information returned by the server.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 6.1.0(23)

Request

Defines an HTTP request.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

constructor

constructor(url: URLOrString, method?: HttpMethod, headers?: RequestHeaders, content?: RequestContent, cookies?: RequestCookies, transferRange?: TransferRange | TransferRange[], configuration?: Configuration)

Provides the constructor used to create a Request object.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

Parameters:

Example:

import { rcp } from '@kit.RemoteCommunicationKit';

let headers: rcp.RequestHeaders = {
  'accept': 'application/json'
};
let content = 'data to send';
let configuration: rcp.Configuration = {
  transfer: {
    timeout: { connectMs: 60000, transferMs: 60000 }
  }
};
let cookies: rcp.RequestCookies = { 'name1': 'value1', 'name2': 'value2' };
let transferRange: rcp.TransferRange = { from: 100, to: 200 };
let req = new rcp.Request('http://example.com', 'POST', headers, content, cookies, transferRange, configuration);

URL

type URL = url.URL

Request address type, which links to URL in @ohos.url.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 4.1.0(11)

X509Cert

type X509Cert = cert.X509Cert

x509 certificate type, which links to X509Cert in @ohos.security.cert.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

File

type File = fs.File

File in the file system, which links to File in @ohos.file.fs.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

RandomAccessFile

type RandomAccessFile = fs.RandomAccessFile

File that can be accessed randomly, which links to RandomAccessFile in @ohos.file.fs.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Stream

type Stream = fs.Stream

Data stream type, which links to Stream in @ohos.file.fs.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

RawDataContent

type RawDataContent = string | ArrayBuffer | object

Defines basic data types of ArkTs.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

FileDescriptor

type FileDescriptor = number

Descriptor of a file, which is an abstract representation for accessing a file or I/O device.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

LocalFile

type LocalFile = FileDescriptor | File | RandomAccessFile

A file-like object that enables users to interact with it using various file descriptors or file objects.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

WriteFile

Provides the function of writing data to a file.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

write

write(buffer: ArrayBuffer): Promise<void | number>

Writes data to a file. This API uses a promise to return the result asynchronously.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

ReadFile

Provides the function for reading data from a file.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

read

read(buffer: ArrayBuffer): Promise<number>

Reads data from a file.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

WriteStream

Provides the function of writing data to a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

write

write(buffer: ArrayBuffer): Promise<void | number>

Writes data from a file to a data stream. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

SyncWriteStream

Provides the function of synchronously writing data to a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

writeSync

writeSync(buffer: ArrayBuffer): void | number

Writes data to a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

ReadStream

Provides the function of reading data from a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

read

read(buffer: ArrayBuffer): Promise<number>

Reads data from a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

SyncReadStream

Provides the function of synchronously reading data from a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

readSync

readSync(buffer: ArrayBuffer): number

Reads data from a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

DownloadedTo

Downloads data to the path specified when the request is initiated through DownloadToFile.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

TargetFile

Saves data to either a specified directory or the default directory.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

TargetFileCallback

type TargetFileCallback = (request: Request, suggestedPath: Path) => TargetFile | Promise<TargetFile>

Callback function that returns a TargetFile object asynchronously using a promise.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

IncomingDataCallback

type IncomingDataCallback = (incomingData: ArrayBuffer) => void | Promise<void>

Callback function for processing downloaded data. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

UploadFromFile

Uploads a file from the client to the server.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

constructor

constructor(fileOrPath: Path | LocalFile | ReadFile)

Provides the constructor used to create an UploadFromFile object.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

UploadFromStream

Uploads a file in stream mode.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

constructor

constructor(stream: Stream | ReadStream | SyncReadStream)

Provides the constructor used to create an UploadFromStream object.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

DownloadToFile

type DownloadToFile = { kind: 'file'; file: TargetFileCallback; } | { kind: 'file'; file: Path; keepLocal?: boolean; } | { kind: 'file'; file: LocalFile | WriteFile; } | { kind: 'folder'; path: Path; keepLocal?: boolean; }

Downloads a file to a specified directory or file. If a file is downloaded to a directory, its name on the server will be retained. The value contains all types in the following table. The kind option is used to specify whether the data will be downloaded to a file or a directory, and the file parameter specifies the target file or directory for the download. For details, please refer to Application Files.

The value contains all types in the following table.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

DownloadToStream

type DownloadToStream = { kind: 'stream'; stream: Stream | WriteStream | SyncWriteStream; }

Downloads a file to a data stream.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

PausePolicy

Defines the request suspension policy.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

ReceivingPauseByTimeout

Defines the policy for suspending request reception by timeout.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

ReceivingPauseByCache

Defines the policy for suspending request reception by cached data size.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

ReceivingPausePolicy

type ReceivingPausePolicy = ReceivingPauseByCache | ReceivingPauseByTimeout

Defines the policy for suspending request reception.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

NetworkOutputQueue

const NetworkOutputQueue: NetworkOutputQueueConstructor

Call new NetworkInputQueue() to create an INetworkOutputQueue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

NetworkOutputQueueConstructor

NetworkOutputQueueConstructor is a constructor of INetworkOutputQueue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

new

new (): INetworkOutputQueue

Creates an INetworkOutputQueue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Returns:

new

new (maxSize: number): INetworkOutputQueue

Creates an INetworkOutputQueue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

new

new (maxSize: number, pausePolicyOverride: ReceivingPausePolicy): INetworkOutputQueue

Creates an INetworkOutputQueue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

INetworkOutputQueue

Defines a read queue for synchronously reading response bodies, which is constructed using new NetworkOutputQueue().

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

read

read(maxBytesToRead: number): ArrayBuffer

Reads a data segment from a queue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

readInto

readInto(buffer: ArrayBuffer): number

Reads data from the queue and stores the data in the specified buffer.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Parameters:

Returns:

Error codes:

For details about the error codes, please refer to API Error Codes.

getStoredBytes

getStoredBytes(): number

Obtains the size of data in the queue.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

Returns:

ResponseBodyDestination

type ResponseBodyDestination = 'array-buffer'| IncomingDataCallback | DownloadToFile | DownloadToStream | INetworkOutputQueue

Sets the destination of a response, so the HTTP client can send response data to the destination.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Collaboration.RemoteCommunication

Since: 5.0.0(12)

URLOrString