# Hardware abstraction layer

The normal work of SDK depends on the hardware and software interfaces provided by the hardware platform, including the microphone, loudspeaker, camera, encryption library and other modules. We design a hardware abstraction layer to provide a consistent interface definition, and the specific interface implementation needs to be provided by the access side of the SDK.

# 1.Module

Header file:wmpf / module.h.

We abstract each module into awx_moduletype. There are currently several modules:

When these Modules are implemented on demand, when you callwx_init (]]to initialize the SDK, the Module is provided to the SDK using the following function pointer:

typedef wx_error_t (*wx_get_module_t)(const char* id,
                                      struct wx_module** module);

When the SDK calls the implemented function, it passes in an ID that needs to return an instance ofwx_modulefor this ID.

parameter

Currently supported module IDs are predefined in each header file:

Return value

The wx_error_tSDK uses this return value to determine whether the requested module is valid.

For example, if a device does not have a camera, then when the SDK requests WX_CAMERA_MODULE_ID, it simply returnsWXERROR_UNIMPLEMENTED.

sample code

// Suppose you have implemented the following module:
extern struct wx_audio_module audio_module;
extern struct wx_camera_module camera_module;
extern struct wx_crypto_module crypto_module;
// The function of HAL getting Module is as follows:
wx_error_t hal_get_module(const char* id, struct wx_module** module_out) {
  if (!strcmp(id, WX_AUDIO_MODULE_ID)) {
    *module_out = (struct wx_module*)&audio_module;
    return WXERROR_OK;
  } else if (!strcmp(id, WX_CAMERA_MODULE_ID)) {
    *module_out = (struct wx_module*)&camera_module;
    return WXERROR_OK;
  } else if (!strcmp(id, WX_CRYPTO_MODULE_ID)) {
    *module_out = (struct wx_module*)&crypto_module;
    return WXERROR_OK;
  }
  // 假设当前设备没有屏幕，因此不需提供 wx_video_module，那么就返回 WXERROR_UNIMPLEMENTED
  return WXERROR_UNIMPLEMENTED;
}

# 2. Audio Module

Header file:wmpf / hardware / audio.h.

Audio module, you need to configure an instance of typewx_audio_module.This type mainly consists of several function pointers used to obtain information about the audio input / output device, or to operate the audio device.

At runtime, VoIP will call these four functions sequentially to complete the configuration of the audio input / output device.

# 2.1get_number_of_devices

Gets the number of audio input-output devices of the specified type.

wx_error_t (*get_number_of_devices)(struct wx_audio_module* module,
                                    wx_audio_device_type_t device_type,
                                    size_t* num_devices_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting number of devices is valid based on this return value

# 2.2get_device_name

Queries for the ID of the index device in the list of audio input / output devices of the specified type (e.g., WX_AUDIO_DEVICE_IN for microphone)

wx_error_t (*get_device_name)(struct wx_audio_module* module,
                              size_t index,
                              wx_audio_device_type_t device_type,
                              char** device_name_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting device ID is valid based on this return value

# 2.3get_device_info

Queries the details of a device that specifies the type and device ID. This function is used to return some audio device information that can be obtained without opening the audio device, such as the supported audio encoding format.

wx_error_t (*get_device_info)(struct wx_audio_module* module,
                              const char* id,
                              wx_audio_device_type_t device_type,
                              const struct wx_metadata** metadata_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting device details are valid based on this return value

# 2.4open

Invokes the specified audio input / output device.

wx_error_t (*open)(struct wx_audio_module* module,
                   const char* id,
                   wx_audio_device_type_t device_type,
                   struct wx_audio_device** device_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting device instance is valid based on this return value

# 2.5wx_audio_device

Struct wx_audio_deviceitself does not have much function, mainly for the description of the device.What really needs to be focused on are its two extension types:wx_audio_device_inandwx_audio_device_out。

# 2.5.1wx_audio_device_in

Abstraction of input devices (e.g. microphones).The key to this type is to provide theopen_input_streamfunction implementation, which the SDK will call at runtime to create an audio input stream object [[]]wx_audio_stream_in。The SDK further controls audio capture using an instance of thewx_audio_stream_inobject.

Microphone devices are created when a VoIP call is dialed and destroyed when a VoIP call is over.

# Parameters for open_input_stream

# wx_audio_stream_in

# wx_audio_stream_in_listener

NOTE:

1. The SDK currently only collects audio data in PCM format, and other audio formats may be added in the future.
2. Config is currently configured with a sampling rate of 16000, a sampling length of 20ms, and 16 bits by default, and may be dynamically adjusted. If the device does not support these audio configurations, the device manufacturer should transform the PCM data themselves.
3. Data callbacks can be understood as non-blocking, that is, network-independent.
4. The data callback provides one frame of audio data that needs to be provided according to the parameters set by theconfig.For example: PCM sampling rate 16000, sampling format 16Bit, sampling length 20ms single channel audio data, including16000 / 1000*20*1*(16 / 8)Data in bytes (sampling rate / 1000*sampling length*] channels * sampling format / 8Bit [).

# 2.5.2 wx_audio_device_out type

Abstraction of a loudspeaker device.The key to this type is to provide an implementation of theopen_output_streamfunction that the runtime SDK will call to create an audio output stream objectwx_audio_stream_out。The SDK further controls audio playback using an instance of thewx_audio_stream_outobject.

A loudspeaker device is created at the beginning of a VoIP call, plays the ringtone first, starts playing the voice at the beginning of the VoIP call, and is destroyed at the end of the VoIP call.

# Parameters for open_output_stream:

# Wx_audio_stream_outType

# Wx_audio_stream_out_listenerType

NOTE:

1. The SDK currently only provides audio data in PCM format, and other audio formats may be added in the future.
2. Config is currently configured with a sampling rate of 16000, a sampling length of 20ms, and 16 bits by default, and may be dynamically adjusted. If the device does not support these audio configurations, the device manufacturer should transform the PCM data themselves.
3. Data callbacks can be understood as non-blocking, that is, network-independent.
4. The buffer passed in by the data callback needs to be large enough to hold a frame of audio data set by the config. For example: PCM sampling rate 16000, sampling format 16Bit, sampling length 20ms single-channel audio data, containing 16000 / 1000_20_1_(16 / 8) bytes of data (sampling rate / 1000_sampling length_channel number_sampling format / 8Bit).

# 3. Signature Algorithm Module

Header file:wmpf / crypto.h.

The SDK relies on the system's built-in signature algorithm, and we provide Demo implementations of OpenSSL, MbedTLS, and WolfSSL in the example directory. If you use the above crypto implementation, you can usually directly use the example code implementation, otherwise refer to the example implementation for adaptation.

Demo implementation:

• example/crypto_mbedtls.c
• example/crypto_openssl.c
• example/crypto_wolfssl.c

# 4. (Optional) Camera module

Header file:wmpf / hardware / camera.h.

Camera module, you need to configure an instance of typewx_camera_module.This type mainly requires you to provide the following function pointers to generate a video stream sent by the device to the phone using the camera device object provided by the device

At runtime, the SDK will call these three functions sequentially to complete the configuration of the camera device.

# 4.1get_number_of_devices

Number of camera devices obtained.

wx_error_t (*get_number_of_devices)(struct wx_camera_module* module,
                                    size_t* num_devices_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting number of devices is valid based on this return value

# 4.2get_device_info

Query for details of the specified camera device.

wx_error_t (*get_device_info)(struct wx_camera_module* module,
                              size_t index,
                              struct wx_camera_device_info* device_info);

parameter

Return value

Wx_error_tSDK determines whether the resulting device details are valid based on this return value

# 4.3open

Call the specified camera device.

wx_error_t (*open)(struct wx_camera_module* module,
                   const char* id,
                   struct wx_camera_device** device_out);

parameter

Return value

Wx_error_tSDK determines whether the resulting device instance is valid based on this return value

# 4.4wx_camera_device

Abstraction of camera devices.The key to this type is the need to provide an implementation of theopen_streamfunction, which the runtime SDK will call to create a video input stream objectwx_camera_stream。The SDK further controls video capture using an instance of thewx_camera_streamobject.

Parameters for open_stream:

# Wx_camera_stream type

# Wx_camera_stream_listener type

NOTE:

1. The SDK currently only collects video data in H264 / H265 format.
2. Data callbacks can be understood as non-blocking, that is, network-independent.
3. The device needs to provide PPS, SPS, I frames on a regular basis (1 second recommended, maximum 5 seconds).
4. Device incoming rotation is only valid on Linux SDK 0xD5000084 and above, WeChat Guest 8.0.41 and above,For older WeChat releases, call the set UIConfig] of the VoIP plug-in on the Weixin Mini Program side to set the angle of swing.

# 5. (Optional) Video Module

Header file:wmpf / hardware / video.h.

Camera module, you need to configure an instance of typewx_video_module.

At runtime, the SDK will call thecreate_output_streamfunction to create a video output stream that outputs the received video recorded by the remote (phone) camera through the stream object.

# 5.1create_output_stream

Create a video output stream.

wx_error_t (*create_output_stream)(struct wx_video_module* module,
                                   const struct wx_video_stream_config* config,
                                   struct wx_video_stream** stream);

parameter

Return value

Wx_error_tSDK determines whether the video output stream is valid based on this return value

# 5.2wx_video_stream