# 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 PublishInfo info, const struct IPublishCallback *cb)	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 CommonDeviceInfo *devInfo, unsigned int num)	int Sets common device information, such as its ID, type, and name.
CreateSessionServer (const char mouduleName, const char sessionName, struct ISessionListener *listener)	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 ``` typedef struct [CommonDeviceInfo](CommonDeviceInfo.md) [CommonDeviceInfo](CommonDeviceInfo.md) ``` **Description:** Defines the type and content of a device to set. ## DeviceType ``` typedef enum [DeviceTypeEnum](Softbus.md#gab20b49630026f3118d6c05b0a022f230) [DeviceType](Softbus.md#ga9334bacb3ded964dc3c3367a6b70bcf4) ``` **Description:** Enumerates device types. ## IPublishCallback ``` typedef struct [IPublishCallback](IPublishCallback.md) [IPublishCallback](IPublishCallback.md) ``` **Description:** Defines the callbacks for successful and failed service publishing. ## PublishInfo ``` typedef struct [PublishInfo](PublishInfo.md) [PublishInfo](PublishInfo.md) ``` **Description:** Defines service provisioning information sent to a discovering device. ## **Enumeration Type Documentation** ## CommonDeviceKey ``` enum [CommonDeviceKey](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 ``` enum [DataBitMap](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 ``` enum [DeviceTypeEnum](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 ``` enum [DiscoverMode](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 ``` enum [ExchanageMedium](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 ``` enum [ExchangeFre](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 ``` enum [PublishFailReason](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\(\) ``` void CloseSession (int sessionId) ``` **Description:** Closes a connected session based on a session ID. **Parameters:**

Name	Description
sessionId	Indicates the session ID.

## CreateSessionServer\(\) ``` int CreateSessionServer (const char * mouduleName, const char * sessionName, struct [ISessionListener](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
moduleName	Indicates 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.
sessionName	Indicates 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.
listener	Indicates 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](Softbus.md#ga225a1e178544457263d94078e638b7b5) ## GetMySessionName\(\) ``` int GetMySessionName (int sessionId, char * sessionName, unsigned int len ) ``` **Description:** Obtains the session name registered by the local device based on the session ID. **Parameters:**

Name	Description
sessionId	Indicates the session ID.
sessionName	Indicates the pointer to the buffer for storing the session name.
len	Indicates the length of the buffer.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## GetPeerDeviceId\(\) ``` int GetPeerDeviceId (int sessionId, char * devId, unsigned int len ) ``` **Description:** Obtains the peer device ID based on a session ID. **Parameters:**

Name	Description
sessionId	Indicates the session ID.
devId	Indicates the pointer to the buffer for storing the device ID.
len	Indicates the length of the buffer.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## GetPeerSessionName\(\) ``` int GetPeerSessionName (int sessionId, char * sessionName, unsigned int len ) ``` **Description:** Obtains the session name registered by the peer device based on the session ID. **Parameters:**

Name	Description
sessionId	Indicates the session ID.
sessionName	Indicates the pointer to the buffer for storing the session name.
len	Indicates the length of the buffer.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## PublishService\(\) ``` int PublishService (const char * moduleName, const struct [PublishInfo](PublishInfo.md) * info, const struct [IPublishCallback](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
moduleName	Indicates the pointer to the module name of the upper-layer service. The value contains a maximum of 63 bytes.
info	Indicates the pointer to the service to publish. For details, see PublishInfo.
cb	Indicates the pointer to the callback for service publishing. For details, see IPublishCallback.

**Returns:** Returns **0** if the operation is successful; returns **-1** otherwise. ## RemoveSessionServer\(\) ``` int RemoveSessionServer (const char * mouduleName, const char * sessionName ) ``` **Description:** Removes a session server based on a module name and session name. **Parameters:**

Name	Description
moduleName	Indicates 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.
sessionName	Indicates 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](Softbus.md#gad7e95cced3378e8f489553d70b121392) ## SendBytes\(\) ``` int SendBytes (int sessionId, const void * data, unsigned int len ) ``` **Description:** Sends data based on a session ID. **Parameters:**

Name	Description
sessionId	Indicates the session ID.
data	Indicates the pointer to the data to send, which cannot be NULL.
len	Indicates 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\(\) ``` int SetCommonDeviceInfo (const struct [CommonDeviceInfo](CommonDeviceInfo.md) * devInfo, unsigned int num ) ``` **Description:** Sets common device information, such as its ID, type, and name. **Parameters:**

Name	Description
devInfo	Indicates the pointer to the device information array.
2	num 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](Softbus.md#ga010557e05b3f0b0b1a05157f1724e13a) ## UnPublishService\(\) ``` int UnPublishService (const char * moduleName, int publishId ) ``` **Description:** Unpublishes a service based on the **publicId** and **moduleName**. **Parameters:**

Name	Description
moduleName	Indicates the pointer to the module name of the upper-layer service. The value contains a maximum of 63 bytes.
publishId	Indicates 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 ``` [DataBitMap](Softbus.md#gab839c7f1fd448f52f003ab0693f27bb4) CapabilityMap::bitmap ``` **Description:** Bitmaps. For details, see [DataBitMap](Softbus.md#gab839c7f1fd448f52f003ab0693f27bb4). ## capability \[1/2\] ``` const char* PublishInfo::capability ``` **Description:** [Service](Service.md) publishing capabilities. For details, see **g\_capabilityMap**. ## capability \[2/2\] ``` char* CapabilityMap::capability ``` **Description:** Capability. For details, see **g\_capabilityMap**. ## capabilityData ``` unsigned char* PublishInfo::capabilityData ``` **Description:** Capability data for service publishing ## dataLen ``` unsigned int PublishInfo::dataLen ``` **Description:** Maximum length of the capability data for service publishing \(2 bytes\) ## devType ``` [DeviceType](Softbus.md#ga9334bacb3ded964dc3c3367a6b70bcf4) DeviceMap::devType ``` **Description:** Enumeration of a device type. Only enumerations defined in **g\_devMap** are supported. ## freq ``` [ExchangeFre](Softbus.md#gacf2c77bd7e2c82784078762978123ea3) PublishInfo::freq ``` **Description:** [Service](Service.md) publishing frequency ## key ``` [CommonDeviceKey](Softbus.md#ga25be99ffbe88e41f7ce51d2678010254) CommonDeviceInfo::key ``` **Description:** Device information type. For details, see [CommonDeviceKey](Softbus.md#ga25be99ffbe88e41f7ce51d2678010254). ## medium ``` [ExchanageMedium](Softbus.md#gaf5c7c122990f0ab5bd46b9bc47b5868b) PublishInfo::medium ``` **Description:** [Service](Service.md) publishing medium ## mode ``` int PublishInfo::mode ``` **Description:** [Service](Service.md) publishing mode, which can be [DISCOVER\_MODE\_PASSIVE](Softbus.md#gga7369479474cf45e9ca9c0f756473c74fac6dc5925b6fb96b8e7e094dcb16b6ebf) or [DISCOVER\_MODE\_ACTIVE](Softbus.md#gga7369479474cf45e9ca9c0f756473c74fa9223119d2d3b76ce474ba46fcc2b2cdb) ## onBytesReceived ``` void(* ISessionListener::onBytesReceived) (int sessionId, const void *data, unsigned int dataLen) ``` **Description:** Called when data is received. This function is used to notify that data is received. **Parameters:**

Name	Description
sessionId	Indicates the session ID.
data	Indicates the pointer to the data received.
dataLen	Indicates the length of the data received.

## onPublishFail ``` void(* IPublishCallback::onPublishFail) (int publishId, [PublishFailReason](Softbus.md#ga6632fcae1db4a3a13370e3fb49e5e620) reason) ``` **Description:** Callback for failed publishing ## onPublishSuccess ``` void(* IPublishCallback::onPublishSuccess) (int publishId) ``` **Description:** Callback for successful publishing ## onSessionClosed ``` 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](Softbus.md#ga5b0c0b334f387f9c2753146ee0890780). **Parameters:**

Name	Description
sessionId	Indicates the session ID.

## onSessionOpened ``` 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
sessionId	Indicates 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](Softbus.md#ga5b0c0b334f387f9c2753146ee0890780) to close the session\). ## publishId ``` int PublishInfo::publishId ``` **Description:** [Service](Service.md) publishing ID ## value \[1/2\] ``` char* DeviceMap::value ``` **Description:** Name of a device type. Only names defined in **g\_devMap** are supported. ## value \[2/2\] ``` const char* CommonDeviceInfo::value ``` **Description:** Content to set