Softbus

Overview

Provides high-speed, secure communication between devices.

This module implements unified distributed communication capability management between nearby devices, and provides link-independent device discovery and transmission interfaces to support service publishing and data transmission.

Since:

1.0

Version:

1.0

Summary

Files

File Name

Description

discovery_service.h

Declares unified device service publishing interfaces.

session.h

Declares unified data transmission interfaces.

Data Structures

Data Structure Name

Description

PublishInfo

Defines service provisioning information sent to a discovering device.

CapabilityMap

Defines the mapping between supported capabilities and bitmaps.

DeviceMap

Defines the mappings between the device type enumerations and device type names.

IPublishCallback

Defines the callbacks for successful and failed service publishing.

CommonDeviceInfo

Defines the type and content of a device to set.

ISessionListener

Defines session callbacks.

Typedefs

Typedef Name

Description

PublishInfo

typedef struct PublishInfo 

Defines service provisioning information sent to a discovering device.

DeviceType

typedef enum DeviceTypeEnum 

Enumerates device types.

IPublishCallback

typedef struct IPublishCallback 

Defines the callbacks for successful and failed service publishing.

CommonDeviceInfo

typedef struct CommonDeviceInfo 

Defines the type and content of a device to set.

Enumerations

Enumeration Name

Description

ExchanageMedium { AUTO = 0, BLE = 1, COAP = 2, USB = 3 }

Enumerates media, such as Bluetooth, Wi-Fi, and USB, used for publishing services.

ExchangeFre { LOW = 0, MID = 1, HIGH = 2, SUPER_HIGH = 3 }

Enumerates frequencies for publishing services. This enumeration is involved only in Bluetooth and is not supported currently.

DiscoverMode { DISCOVER_MODE_PASSIVE = 0x55, DISCOVER_MODE_ACTIVE = 0xAA }

Enumerates the modes in which services are published. The publishing service supports the passive mode. Lite devices support the passive mode only.

PublishFailReason { PUBLISH_FAIL_REASON_NOT_SUPPORT_MEDIUM = 1, PUBLISH_FAIL_REASON_PARAMETER_INVALID = 2, PUBLISH_FAIL_REASON_UNKNOWN = 0xFF }

Enumerates failure reasons for publishing services.

DataBitMap {   HICALL_CAPABILITY_BITMAP = 0, PROFILE_CAPABILITY_BITMAP = 1, HOMEVISIONPIC_CAPABILITY_BITMAP = 2, CASTPLUS_CAPABILITY_BITMAP,   AA_CAPABILITY_BITMAP, DVKIT_CAPABILITY_BITMAP, DDMP_CAPABILITY_BITMAP }

Enumerates supported capabilities published by a device.

DeviceTypeEnum {   UNKOWN = 0x00, PHONE = 0x0E, PAD = 0x11, TV = 0x9C,   PC = 0x0C, AUDIO = 0x0A, CAR = 0x83, L0 = 0xF1,   L1 = 0xF2 }

Enumerates device types.

CommonDeviceKey { COMM_DEVICE_KEY_DEVID = 0, COMM_DEVICE_KEY_DEVTYPE = 1, COMM_DEVICE_KEY_DEVNAME = 2, COMM_DEVICE_KEY_MAX }

Enumerates device information, such as its ID, type, and name.

Functions

Function Name

Description

PublishService (const char moduleName, const struct PublishInfoinfo, const struct IPublishCallbackcb)

int 

Publishes a service to the discovering device in the LAN.

UnPublishService (const char moduleName, int publishId)

int 

Unpublishes a service based on the publicId and moduleName.

SetCommonDeviceInfo (const struct CommonDeviceInfodevInfo, unsigned int num)

int 

Sets common device information, such as its ID, type, and name.

CreateSessionServer (const char mouduleName, const char sessionName, struct ISessionListenerlistener)

int 

Creates a session server based on a module name and session name.

RemoveSessionServer (const char mouduleName, const char sessionName)

int 

Removes a session server based on a module name and session name.

SendBytes (int sessionId, const void data, unsigned int len)

int 

Sends data based on a session ID.

GetMySessionName (int sessionId, char sessionName, unsigned int len)

int 

Obtains the session name registered by the local device based on the session ID.

GetPeerSessionName (int sessionId, char sessionName, unsigned int len)

int 

Obtains the session name registered by the peer device based on the session ID.

GetPeerDeviceId (int sessionId, char devId, unsigned int len)

int 

Obtains the peer device ID based on a session ID.

CloseSession (int sessionId)

void 

Closes a connected session based on a session ID.

Details

Typedef Documentation

CommonDeviceInfo

  1. typedefstruct[CommonDeviceInfo]($api-api-LinkIoT-CommonDeviceInfo.md)[CommonDeviceInfo]($api-api-LinkIoT-CommonDeviceInfo.md)

Description:

Defines the type and content of a device to set.

DeviceType

  1. typedefenum[DeviceTypeEnum]($api-api-LinkIoT-Softbus.md#gab20b49630026f3118d6c05b0a022f230) [DeviceType]($api-api-LinkIoT-Softbus.md#ga9334bacb3ded964dc3c3367a6b70bcf4)

Description:

Enumerates device types.

IPublishCallback

  1. typedefstruct[IPublishCallback]($api-api-LinkIoT-IPublishCallback.md)[IPublishCallback]($api-api-LinkIoT-IPublishCallback.md)

Description:

Defines the callbacks for successful and failed service publishing.

PublishInfo

  1. typedefstruct[PublishInfo]($api-api-LinkIoT-PublishInfo.md)[PublishInfo]($api-api-LinkIoT-PublishInfo.md)

Description:

Defines service provisioning information sent to a discovering device.

Enumeration Type Documentation

CommonDeviceKey

  1. enum[CommonDeviceKey]($api-api-LinkIoT-Softbus.md#ga25be99ffbe88e41f7ce51d2678010254)

Description:

Enumerates device information, such as its ID, type, and name.

Enumerator

Description

COMM_DEVICE_KEY_DEVID 

Device ID. The value contains a maximum of 64 characters.

COMM_DEVICE_KEY_DEVTYPE 

Device type. Currently, only ddmpCapability is supported.

COMM_DEVICE_KEY_DEVNAME 

Device name. The value contains a maximum of 63 characters.

COMM_DEVICE_KEY_MAX 

Reserved

DataBitMap

  1. enum[DataBitMap]($api-api-LinkIoT-Softbus.md#gab839c7f1fd448f52f003ab0693f27bb4)

Description:

Enumerates supported capabilities published by a device.

Enumerator

Description

HICALL_CAPABILITY_BITMAP 

MeeTime

PROFILE_CAPABILITY_BITMAP 

Video reverse connection in the smart domain

HOMEVISIONPIC_CAPABILITY_BITMAP 

Gallery in Vision

CASTPLUS_CAPABILITY_BITMAP 

cast+

AA_CAPABILITY_BITMAP 

Input method in Vision

DVKIT_CAPABILITY_BITMAP 

Device virtualization tool package

DDMP_CAPABILITY_BITMAP 

Distributed middleware

DeviceTypeEnum

  1. enum[DeviceTypeEnum]($api-api-LinkIoT-Softbus.md#gab20b49630026f3118d6c05b0a022f230)

Description:

Enumerates device types.

Enumerator

Description

UNKOWN 

Unknown

PHONE 

Smartphone

PAD 

Tablet

TV 

Smart TV

PC 

PC

AUDIO 

Audio device

CAR 

Vehicle-mounted device

L0 

Light device L0

L1 

Light device L1

DiscoverMode

  1. enum[DiscoverMode]($api-api-LinkIoT-Softbus.md#ga7369479474cf45e9ca9c0f756473c74f)

Description:

Enumerates the modes in which services are published. The publishing service supports the passive mode. Lite devices support the passive mode only.

Enumerator

Description

DISCOVER_MODE_PASSIVE 

Passive

DISCOVER_MODE_ACTIVE 

Proactive

ExchanageMedium

  1. enum[ExchanageMedium]($api-api-LinkIoT-Softbus.md#gaf5c7c122990f0ab5bd46b9bc47b5868b)

Description:

Enumerates media, such as Bluetooth, Wi-Fi, and USB, used for publishing services.

Currently, the media can only be set to coap.

Enumerator

Description

AUTO 

Automatic medium selection

BLE 

Bluetooth

COAP 

Wi-Fi

USB 

USB

ExchangeFre

  1. enum[ExchangeFre]($api-api-LinkIoT-Softbus.md#gacf2c77bd7e2c82784078762978123ea3)

Description:

Enumerates frequencies for publishing services. This enumeration is involved only in Bluetooth and is not supported currently.

Enumerator

Description

LOW 

Low

MID 

Medium

HIGH 

High

SUPER_HIGH 

Super-high

PublishFailReason

  1. enum[PublishFailReason]($api-api-LinkIoT-Softbus.md#ga6632fcae1db4a3a13370e3fb49e5e620)

Description:

Enumerates failure reasons for publishing services.

The failure reason is returned to the caller through the callback function.

Enumerator

Description

PUBLISH_FAIL_REASON_NOT_SUPPORT_MEDIUM 

Unsupported medium

PUBLISH_FAIL_REASON_PARAMETER_INVALID 

Invalid parameter

PUBLISH_FAIL_REASON_UNKNOWN 

Unknown reason

Function Documentation

CloseSession()

  1. voidCloseSession(int sessionId)

Description:

Closes a connected session based on a session ID.

Parameters:

Name

Description

sessionIdIndicates the session ID.

CreateSessionServer()

  1. intCreateSessionServer(constchar* mouduleName,constchar* sessionName,struct[ISessionListener]($api-api-LinkIoT-ISessionListener.md)* listener )

Description:

Creates a session server based on a module name and session name.

A maximum of 18 session servers can be created.

Parameters:

Name

Description

moduleNameIndicates the pointer to the module name, which can be used to check whether the session server is in this module. The value cannot be empty and can contain a maximum of 64 characters.
sessionNameIndicates the pointer to the session name, which is the unique ID of the session server. The value cannot be empty and can contain a maximum of 64 characters.
listenerIndicates the pointer to the session callback structure, which cannot be empty.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

See also:

RemoveSessionServer

GetMySessionName()

  1. intGetMySessionName(int sessionId,char* sessionName,unsignedint len )

Description:

Obtains the session name registered by the local device based on the session ID.

Parameters:

Name

Description

sessionIdIndicates the session ID.
sessionNameIndicates the pointer to the buffer for storing the session name.
lenIndicates the length of the buffer.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

GetPeerDeviceId()

  1. intGetPeerDeviceId(int sessionId,char* devId,unsignedint len )

Description:

Obtains the peer device ID based on a session ID.

Parameters:

Name

Description

sessionIdIndicates the session ID.
devIdIndicates the pointer to the buffer for storing the device ID.
lenIndicates the length of the buffer.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

GetPeerSessionName()

  1. intGetPeerSessionName(int sessionId,char* sessionName,unsignedint len )

Description:

Obtains the session name registered by the peer device based on the session ID.

Parameters:

Name

Description

sessionIdIndicates the session ID.
sessionNameIndicates the pointer to the buffer for storing the session name.
lenIndicates the length of the buffer.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

PublishService()

  1. intPublishService(constchar* moduleName,conststruct[PublishInfo]($api-api-LinkIoT-PublishInfo.md)* info,conststruct[IPublishCallback]($api-api-LinkIoT-IPublishCallback.md)* cb )

Description:

Publishes a service to the discovering device in the LAN.

The publicId and moduleName uniquely identify a service. A maximum of three services can be published.

Parameters:

Name

Description

moduleNameIndicates the pointer to the module name of the upper-layer service. The value contains a maximum of 63 bytes.
infoIndicates the pointer to the service to publish. For details, see PublishInfo.
cbIndicates the pointer to the callback for service publishing. For details, see IPublishCallback.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

RemoveSessionServer()

  1. intRemoveSessionServer(constchar* mouduleName,constchar* sessionName )

Description:

Removes a session server based on a module name and session name.

Parameters:

Name

Description

moduleNameIndicates the pointer to the name of the registered module, which can be used to check whether the session server is in this module. The value cannot be empty and can contain a maximum of 64 characters.
sessionNameIndicates the pointer to the session name. The value cannot be empty and can contain a maximum of 64 characters.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

See also:

CreateSessionServer

SendBytes()

  1. intSendBytes(int sessionId,constvoid* data,unsignedint len )

Description:

Sends data based on a session ID.

Parameters:

Name

Description

sessionIdIndicates the session ID.
dataIndicates the pointer to the data to send, which cannot be NULL.
lenIndicates the length of the data to send. The maximum length cannot exceed 984 characters.

Returns:

Returns 0 if the function is called successfully; returns -1 otherwise.

SetCommonDeviceInfo()

  1. intSetCommonDeviceInfo(conststruct[CommonDeviceInfo]($api-api-LinkIoT-CommonDeviceInfo.md)* devInfo,unsignedint num )

Description:

Sets common device information, such as its ID, type, and name.

Parameters:

Name

Description

devInfoIndicates the pointer to the device information array.
2num Indicates the number of elements in the device information array. If the value is inconsistent with the length of the device information array, the program breaks down.

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

See also:

PublishService

UnPublishService()

  1. intUnPublishService(constchar* moduleName,int publishId )

Description:

Unpublishes a service based on the publicId and moduleName.

Parameters:

Name

Description

moduleNameIndicates the pointer to the module name of the upper-layer service. The value contains a maximum of 63 bytes.
publishIdIndicates the ID of the service to unpublish. The value must be greater than 0.

Returns:

Returns 0 if the operation is successful; returns a non-zero value otherwise.

Variable Documentation

bitmap

  1. [DataBitMap]($api-api-LinkIoT-Softbus.md#gab839c7f1fd448f52f003ab0693f27bb4) CapabilityMap::bitmap

Description:

Bitmaps. For details, see DataBitMap.

capability [1/2]

  1. constchar*PublishInfo::capability

Description:

Service publishing capabilities. For details, see g_capabilityMap.

capability [2/2]

  1. char*CapabilityMap::capability

Description:

Capability. For details, see g_capabilityMap.

capabilityData

  1. unsignedchar*PublishInfo::capabilityData

Description:

Capability data for service publishing

dataLen

  1. unsignedintPublishInfo::dataLen

Description:

Maximum length of the capability data for service publishing (2 bytes)

devType

  1. [DeviceType]($api-api-LinkIoT-Softbus.md#ga9334bacb3ded964dc3c3367a6b70bcf4) DeviceMap::devType

Description:

Enumeration of a device type. Only enumerations defined in g_devMap are supported.

freq

  1. [ExchangeFre]($api-api-LinkIoT-Softbus.md#gacf2c77bd7e2c82784078762978123ea3) PublishInfo::freq

Description:

Service publishing frequency

key

  1. [CommonDeviceKey]($api-api-LinkIoT-Softbus.md#ga25be99ffbe88e41f7ce51d2678010254) CommonDeviceInfo::key

Description:

Device information type. For details, see CommonDeviceKey.

medium

  1. [ExchanageMedium]($api-api-LinkIoT-Softbus.md#gaf5c7c122990f0ab5bd46b9bc47b5868b) PublishInfo::medium

Description:

Service publishing medium

mode

  1. intPublishInfo::mode

Description:

Service publishing mode, which can be DISCOVER_MODE_PASSIVE or DISCOVER_MODE_ACTIVE

onBytesReceived

  1. void(*ISessionListener::onBytesReceived)(int sessionId,constvoid*data,unsignedint dataLen)

Description:

Called when data is received.

This function is used to notify that data is received.

Parameters:

Name

Description

sessionIdIndicates the session ID.
dataIndicates the pointer to the data received.
dataLenIndicates the length of the data received.

onPublishFail

  1. void(*IPublishCallback::onPublishFail)(int publishId,[PublishFailReason]($api-api-LinkIoT-Softbus.md#ga6632fcae1db4a3a13370e3fb49e5e620) reason)

Description:

Callback for failed publishing

onPublishSuccess

  1. void(*IPublishCallback::onPublishSuccess)(int publishId)

Description:

Callback for successful publishing

onSessionClosed

  1. void(*ISessionListener::onSessionClosed)(int sessionId)

Description:

Called when a session is closed.

This function can be used to release resources related to the session. You do not need to call CloseSession.

Parameters:

Name

Description

sessionIdIndicates the session ID.

onSessionOpened

  1. int(*ISessionListener::onSessionOpened)(int sessionId)

Description:

Called when a session is opened.

This function can be used to verify the session or initialize resources related to the session.

Parameters:

Name

Description

sessionIdIndicates the session ID.

Returns:

Returns 0 if the session connection is accepted; returns a non-zero value otherwise (you do not need to call CloseSession to close the session).

publishId

  1. intPublishInfo::publishId

Description:

Service publishing ID

value [1/2]

  1. char*DeviceMap::value

Description:

Name of a device type. Only names defined in g_devMap are supported.

value [2/2]

  1. constchar*CommonDeviceInfo::value

Description:

Content to set