提交 24d6cc6a 编写于 作者: S shawn_he

update docs

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 b07b2132
# Connectivity
- [IPC & RPC]
- [IPC & RPC Overview](ipc-rpc-overview.md)
- [IPC & RPC Development](ipc-rpc-development-guideline.md)
- [Subscribing to State Changes of a Remote Object](subscribe-remote-state.md)
# Network and Connectivity
- Network Management
- [Network Management Overview](net-mgmt-overview.md)
- [HTTP Data Request](http-request.md)
- [WebSocket Connection](websocket-connection.md)
- [Socket Connection](socket-connection.md)
- IPC & RPC
- [IPC & RPC Overview](ipc-rpc-overview.md)
- [IPC & RPC Development Guidelines](ipc-rpc-development-guideline.md)
- [Subscribing to State Changes of a Remote Object](subscribe-remote-state.md)
# HTTP Data Request
## Use Cases
An application can initiate a data request over HTTP. Common HTTP methods include **GET**, **POST**, **OPTIONS**, **HEAD**, **PUT**, **DELETE**, **TRACE**, and **CONNECT**.
## Available APIs
The HTTP request function is mainly implemented by the HTTP module.
To use related APIs, you must declare the **ohos.permission.INTERNET** permission.
The following table describes the related APIs.
| API | Description |
| ----------------------------------------- | ----------------------------------- |
| createHttp() | Creates an HTTP request. |
| request() | Initiates an HTTP request to a given URL. |
| destroy() | Destroys an HTTP request. |
| on(type: 'headersReceive') | Registers an observer for HTTP Response Header events. |
| off(type: 'headersReceive') | Unregisters the observer for HTTP Response Header events.|
## How to Develop
1. Import the required HTTP module.
2. Create an **HttpRequest** object.
3. (Optional) Listen for HTTP Response Header events.
4. Initiates an HTTP request to a given URL.
5. (Optional) Process the HTTP Response Header event and the return result of the HTTP request.
```js
import http from '@ohos.net.http';
// Each HttpRequest corresponds to an HttpRequestTask object and cannot be reused.
let httpRequest = http.createHttp();
// Subscribe to the HTTP response header, which is returned earlier than HttpRequest. You can subscribe to HTTP Response Header events based on service requirements.
// on('headerReceive', AsyncCallback) will be replaced by on('headersReceive', Callback) in API version 8. 8+
httpRequest.on('headersReceive', (header) => {
console.info('header: ' + JSON.stringify(header));
});
httpRequest.request(
// Set the URL of the HTTP request. You need to define the URL. Set the parameters of the request in extraData.
"EXAMPLE_URL",
{
method: http.RequestMethod.POST, // Optional. The default value is http.RequestMethod.GET.
// You can add the header field based on service requirements.
header: {
'Content-Type': 'application/json'
},
// This field is used to transfer data when the POST request is used.
extraData: {
"data": "data to send",
},
connectTimeout: 60000, // Optional. The default value is 60000, in ms.
readTimeout: 60000, // Optional. The default value is 60000, in ms.
}, (err, data) => {
if (!err) {
// data.result contains the HTTP response. Parse the response based on service requirements.
console.info('Result:' + data.result);
console.info('code:' + data.responseCode);
// data.header contains the HTTP response header. Parse the content based on service requirements.
console.info('header:' + JSON.stringify(data.header));
console.info('cookies:' + data.cookies); // 8+
} else {
console.info('error:' + JSON.stringify(err));
// Call the destroy() method to release resources after the call is complete.
httpRequest.destroy();
}
}
);
```
# Network Management Overview
Network management functions include:
- [HTTP Data Request](http-request.md): Initiates a data request through HTTP.
- [WebSocket Connection](websocket-connection.md): Establishes a bidirectional connection between the server and client through WebSocket.
- [Socket Connection](socket-connection.md): Transmits data through Socket.
## Constraints
To use the functions of the network management module, you must obtain the permissions listed in the following table.
| Permission | Description |
| -------------------------------- | -------------------------------------- |
| ohos.permission.GET_NETWORK_INFO | Allows an application to obtain the network connection information. |
| ohos.permission.SET_NETWORK_INFO | Allows an application to modify the network connection state. |
| ohos.permission.INTERNET | Allows an application to open network sockets to connect to the network.|
# Socket Connection
## Use Cases
Your application can transmit data through Socket connections. Currently, the TCP and UDP protocols are supported.
## Available APIs
The Socket connection function is mainly implemented by the Socket module. The following table describes the related APIs.
| API| Description|
| -------- | -------- |
| constructUDPSocketInstance() | Creates a **UDPSocket** object.|
| constructTCPSocketInstance() | Creates a **TCPSocket** object.|
| bind() | Binds the IP address and port number.|
| send() | Sends data.|
| close() | Closes a Socket connection.|
| getState() | Obtains the Socket connection status.|
| connect() | Connects to the specified IP address and port. This function is supported only for TCP.|
| getRemoteAddress() | Obtains the peer address of the Socket connection. This function is supported only for TCP. The **connect** API must have been called before you use this API.|
| on(type:&nbsp;'message') | Enables listening for **message** events of the Socket connection.|
| off(type:&nbsp;'message') | Disables listening for **message** events of the Socket connection.|
| on(type:&nbsp;'close') | Enables listening for **close** events of the Socket connection.|
| off(type:&nbsp;'close') | Disables listening for **close** events of the Socket connection.|
| on(type:&nbsp;'error') | Enables listening for **error** events of the Socket connection.|
| off(type:&nbsp;'error') | Disables listening for **error** events of the Socket connection.|
| on(type:&nbsp;'listening') | Enables listening for **listening** events of the UDPSocket connection. |
| off(type:&nbsp;'listening') | Disables listening for **listening** events of the UDPSocket connection. |
| on(type:&nbsp;'connect') | Enables listening for **connect** events of the TCPSocket connection. |
| off(type:&nbsp;'connect') | Disables listening for **connect** events of the TCPSocket connection.|
## How to Develop
The implementation is similar for UDPSocket and TCPSocket. The following uses the TCPSocket as an example.
1. Import the required Socket module.
2. Create a **TCPSocket** object.
3. (Optional) Enable listening for TCPSocket events.
4. Bind the IP address and port number. The port number can be specified or randomly allocated by the system.
5. Set up a connection to the specified IP address and port number.
6. Send data.
7. Enable the TCPSocket connection to be automatically closed after use.
```js
import socket from '@ohos.net.socket'
// Create a TCPSocket object.
let tcp = socket.constructTCPSocketInstance();
// Enable listening for TCPSocket events.
tcp.on('message', value => {
console.log("on message")
let buffer = value.message
let dataView = new DataView(buffer)
let str = ""
for (let i = 0;i < dataView.byteLength; ++i) {
str += String.fromCharCode(dataView.getUint8(i))
}
console.log("on connect recevied:" + str)
});
tcp.on('connect', () => {
console.log("on connect")
});
tcp.on('close', () => {
console.log("on close")
});
// Bind the IP address and port number.
let bindAddress = {
address: '192.168.xx.xx',
port: 1234, // Bound port, for example, 1234.
family: 1
};
tcp.bind(bindAddress, err => {
if (err) {
console.log('bind fail');
return;
}
console.log('bind success');
// Set up a connection to the specified IP address and port number.
let connectAddress = {
address: '192.168.xx.xx',
port: 5678, // Connection port, for example, 5678.
family: 1
};
tcp.connect({
address: connectAddress, timeout: 6000
}, err => {
if (err) {
console.log('connect fail');
return;
}
console.log('connect success');
// Send data.
tcp.send({
data: 'Hello, server!'
}, err => {
if (err) {
console.log('send fail');
return;
}
console.log('send success');
})
});
});
// Enable the TCPSocket connection to be automatically closed after use. Then, disable listening for TCPSocket events.
setTimeout(() => {
tcp.close((err) => {
console.log('close socket.')
});
tcp.off('message');
tcp.off('connect');
tcp.off('close');
}, 30 * 1000);
```
# WebSocket Connection
## Use Cases
You can use WebSocket to establish a bidirectional connection between a server and a client. Before doing this, you need to use the **createWebSocket** API to create a **WebSocket** object and then use the **connect** API to connect to the server. If the connection is successful, the client will receive a callback of the **open** event. Then, the client can communicate with the server using the **send** API. When the server sends a message to the client, the client will receive a callback of the **message** event. If the client no longer needs this connection, it can call the **close** API to disconnect from the server. Then, the client will receive a callback of the **close** event.
If an error occurs in any of the preceding processes, the client will receive a callback of the **error** event.
## Available APIs
The WebSocket connection function is mainly implemented by the WebSocket module. To use related APIs, you must declare the **ohos.permission.INTERNET** permission. The following table describes the related APIs.
| API| Description|
| -------- | -------- |
| createWebSocket() | Creates a WebSocket connection.|
| connect() | Establishes a WebSocket connection to a given URL.|
| send() | Sends data through the WebSocket connection.|
| close() | Closes a WebSocket connection.|
| on(type:&nbsp;'open') | Enables listening for **open** events of a WebSocket connection.|
| off(type:&nbsp;'open') | Disables listening for **open** events of a WebSocket connection.|
| on(type:&nbsp;'message') | Enables listening for **message** events of a WebSocket connection.|
| off(type:&nbsp;'message') | Disables listening for **message** events of a WebSocket connection.|
| on(type:&nbsp;'close') | Enables listening for **close** events of a WebSocket connection.|
| off(type:&nbsp;'close') | Disables listening for **close** events of a WebSocket connection.|
| on(type:&nbsp;'error') | Enables listening for **error** events of a WebSocket connection.|
| off(type:&nbsp;'error') | Disables listening for **error** events of a WebSocket connection.|
## How to Develop
1. Import the required WebSocket module.
2. Create a **WebSocket** object.
3. (Optional) Subscribe to WebSocket open, message, close, and error events.
4. Establish a WebSocket connection to a given URL.
5. Close the WebSocket connection if it is no longer needed.
```js
import webSocket from '@ohos.net.webSocket';
var defaultIpAddress = "ws://";
let ws = webSocket.createWebSocket();
ws.on('open', (err, value) => {
console.log("on open, status:" + JSON.stringify(value));
// When receiving the on('open') event, the client can use the send() API to communicate with the server.
ws.send("Hello, server!", (err, value) => {
if (!err) {
console.log("send success");
} else {
console.log("send fail, err:" + JSON.stringify(err));
}
});
});
ws.on('message', (err, value) => {
console.log("on message, message:" + value);
// When receiving the `bye` message (the actual message name may differ) from the server, the client proactively disconnects from the server.
if (value === 'bye') {
ws.close((err, value) => {
if (!err) {
console.log("close success");
} else {
console.log("close fail, err is " + JSON.stringify(err));
}
});
}
});
ws.on('close', (err, value) => {
console.log("on close, code is " + value.code + ", reason is " + value.reason);
});
ws.on('error', (err) => {
console.log("on error, error:" + JSON.stringify(err));
});
ws.connect(defaultIpAddress, (err, value) => {
if (!err) {
console.log("connect success");
} else {
console.log("connect fail, err:" + JSON.stringify(err));
}
});
```
# Telephony
- [Telephony Service Overview](telephony-overview.md)
- [Redirecting to the Dial Screen](jumping-to-the-dial-screen.md)
- [Obtaining Current Cellular Network Signal Information](cellular-network-signal-info.md)
# Obtaining Current Cellular Network Signal Information
## Use Cases
Applications always need to obtain signal information of the registered cellular network to obtain the network quality. You can use this service to obtain the network signal information for the specified SIM card.
## Available APIs
The radio module provides you with APIs to obtain network signal information. The observer module provides APIs to register or unregister the observer for cellular network status changes. The following table describes the related APIs.
| Category| API| Description| Required Permission|
| -------- | -------- | -------- | -------- |
| Obtaining a **SignalInformation** object| radio.getSignalInformation​​() | Obtains the signal strength of the currently registered cellular network.| N/A|
| Registering the observer for signal information changes| observer.on('signalInfoChange') | Registers the observer for signal information changes.| N/A|
| Unregistering the observer for signal information changes| observer.off('signalInfoChange') | Unregisters the observer for signal information changes.| N/A|
## How to Develop
1. Import required modules.
2. Call the **getSignalInformation()** API to obtain the **SignalInformation** list.
3. Traverse the **SignalInformation** list to obtain the signal strength for each radio access technology (RAT) indicated by **signalType**.
4. (Optional) Register the observer for signal information changes.
```js
import radio from '@ohos.telephony.radio'
import observer from '@ohos.telephony.observer';
// Obtain the signal strength of the specified SIM card, for example, card 1.
let slotId = 0;
radio.getSignalInformation(slotId, (err, data) => {
if (!err) {
console.log("get signal information success.");
// Traverse the signal information list to obtain the signal strength for each RAT.
for (let j = 0; j < data.length; j++) {
console.log("type:" + data[j].signalType + ", level:" + data[j].signalLevel);
}
} else {
console.log("get signal information fail, err is:" + JSON.stringify(err));
}
});
// (Optional) Register the observer for signal information changes.
observer.on("signalInfoChange", (data) => {
console.log("signal info change, data is:" + JSON.stringify(data));
});
```
# Redirecting to the Dial Screen
You can use this service for your application to redirect users to the dial screen and display the dialed number. When the **makeCall** API is called, the phone or tablet will automatically display the dial screen. On this screen, the user can choose to make an audio or video call and specify the SIM card.
## Available APIs
The call module provides APIs for call management. The observer module provides APIs to register or unregister the observer for cellular network status changes. The following table describes the related APIs.
| Category| API| Description| Required Permission|
| -------- | -------- | -------- | -------- |
| Checking call capabilities| call.hasVoiceCapability() | Checks whether the voice call function is supported.| N/A|
| Redirecting to the dial screen| call.makeCall() | Enables redirection to the dial screen and display of the dialed number.| N/A|
| Registering the observer for call service status changes| observer.on('callStateChange') | Registers the observer for call service status changes.| ohos.permission.READ_CALL_LOG (required for obtaining phone numbers)|
| Unregistering the observer for call service status changes| observer.off('callStateChange') | Unregisters the observer for call service status changes.| N/A|
## How to Develop
1. Import required modules.
2. Invoke the **hasVoiceCapability()** API to check whether the call function is supported. If supported, go to step 3; otherwise, calls will be rejected.
3. Enable redirection to the dial screen and display of the dialed number.
4. (Optional) Register the observer for call service status changes.
```js
// Import the required modules.
import call from '@ohos.telephony.call';
import observer from '@ohos.telephony.observer';
// Check whether the voice call function is supported.
let isSupport = call.hasVoiceCapability();
if (!isSupport) {
console.log("not support voice capability, return.");
return;
}
// If the voice call function is supported, the user will be redirected to the dial screen and the dialed number is displayed.
call.makeCall("13xxxx", (err)=> {
if (!err) {
console.log("make call success.");
} else {
console.log("make call fail, err is:" + JSON.stringify(err));
}
});
// (Optional) Register the observer for call service status changes.
observer.on("callStateChange", (data) => {
console.log("call state change, data is:" + JSON.stringify(data));
});
```
# Telephony Service Overview
The Telephony subsystem provides a series of APIs for [making calls](../reference/apis/js-apis-call.md), [obtaining current cellular network signal information](../reference/apis/js-apis-telephony-data.md) and [managing SIM cards](../reference/apis/js-apis-sim.md).
Your application can call related APIs to obtain the name of the currently registered network, network service status, signal strength, and SIM card information. For details, see [Obtaining Current Cellular Network Signal Information](cellular-network-signal-info.md).
To make calls, your application needs to declear the **ohos.permission.PLACE_CALL** permission. It is recommended that the application use **makeCall()** to redirect users to the dial screen and display the dialed number. For details, see [Redirecting to the Dial Screen](jumping-to-the-dial-screen.md).
## Constraints
The accommodating device must be equipped with the following hardware:
A modem and a SIM card capable of independent cellular communication.
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册