Link IoT Edge：SDK for C

Topik ini menjelaskan cara menggunakan SDK for C dan API terkait. IoT Edge menyediakan SDK for C bernama linkedge-thing-access-sdk-c.

/*
     * Fungsi callback yang digunakan untuk mendapatkan properti perangkat yang didefinisikan dalam TSL perangkat. Pengembang driver harus mengimplementasikan logika bisnis untuk mendapatkan properti tersebut.
     * 
     * Saat Link IoT Edge perlu mendapatkan properti suatu perangkat, SDK memanggil fungsi ini untuk mengambil data, mengurai data ke dalam format tetap, lalu mengirimkannya kembali ke Link IoT Edge.
     * Pengembang harus mengidentifikasi perangkat berdasarkan ID perangkat dan nama properti. Kemudian, pengembang harus menetapkan nilai properti sesuai dengan format @device_data_t.
     *
     * @dev_handle: perangkat dari mana Link IoT Edge mendapatkan properti.
     * @properties: nilai properti. Pengembang driver harus memperbarui nilai parameter properties berdasarkan nilai properti yang diperoleh.
     * @properties_count: jumlah properti.
     * @usr_data: data pribadi yang ditentukan pengguna saat perangkat didaftarkan.
     * Jika semua properti berhasil diperoleh, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan. Untuk informasi lebih lanjut, lihat makro kode kesalahan yang didefinisikan dalam file le_error.h.
     * */
typedef int (*get_properties_callback)(device_handle_t dev_handle, 
                                       leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * Fungsi callback yang digunakan untuk menetapkan properti yang didefinisikan dalam TSL. Pengembang driver harus mengimplementasikan logika bisnisnya.
     * 
     * Saat Link IoT Edge perlu menetapkan properti suatu perangkat, SDK memanggil fungsi ini dan mengirimkan data ke aplikasi edge.
     * Pengembang harus menggunakan fungsi ini untuk menetapkan properti perangkat.
     *
     * @dev_handle: perangkat yang propertinya akan ditetapkan oleh Link IoT Edge.
     * @properties: nilai properti baru yang akan ditetapkan untuk perangkat.
     * @properties_count: jumlah properti.
     * @usr_data: data pribadi yang ditentukan pengguna saat perangkat didaftarkan.
     * 
     * Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan. Untuk informasi lebih lanjut, lihat makro kode kesalahan yang didefinisikan dalam file le_error.h.
     * */
typedef int (*set_properties_callback)(device_handle_t dev_handle, 
                                       const leda_device_data_t properties[], 
                                       int properties_count, 
                                       void *usr_data);

/*
     * Fungsi callback yang digunakan untuk memanggil layanan berdasarkan layanan yang didefinisikan dalam TSL perangkat. Pengembang driver harus mengimplementasikan logika bisnis untuk layanan tersebut.
     * 
     * Saat Link IoT Edge perlu memanggil layanan suatu perangkat, SDK memanggil fungsi ini untuk meneruskan parameter layanan tertentu ke aplikasi.
     * Pengembang harus memanggil layanan dalam fungsi ini dan menetapkan nilai kembali layanan ke parameter output_data sesuai dengan format @device_data_t. 
     *
     * @dev_handle: perangkat spesifik dari mana Link IoT Edge memanggil layanan.
     * @service_name: nama layanan. Nama layanan harus sama dengan yang ada di TSL.
     * @data: parameter layanan. Parameter harus sama dengan parameter dalam TSL perangkat.
     * @data_count: jumlah parameter layanan.
     * @output_data: data keluaran. Pengembang harus menetapkan parameter ini ke nilai kembali layanan sesuai dengan format yang didefinisikan dalam TSL perangkat.
     * @usr_data: data pribadi yang ditentukan pengguna saat perangkat didaftarkan.
     * 
     * Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan. Untuk informasi lebih lanjut, lihat makro kode kesalahan yang didefinisikan dalam file le_error.h.
     * */
typedef int (*call_service_callback)(device_handle_t dev_handle, 
                                     const char *service_name, 
                                     const leda_device_data_t data[], 
                                     int data_count, 
                                     leda_device_data_t output_data[], 
                                     void *usr_data);

/*
 * Melaporkan properti. Kemampuan pelaporan properti ditentukan dalam model TSL produk tempat perangkat tersebut terdaftar.
 *
 * Melaporkan properti. Satu atau beberapa properti dapat dilaporkan sekaligus.
 *
 * dev_handle: pengidentifikasi unik perangkat di Link IoT Edge.
 * properties: array properti @leda_device_data_t.
 * properties_count: jumlah properti.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 *
 */
int leda_report_properties(device_handle_t dev_handle, const leda_device_data_t properties[], int properties_count);

/*
 * Melaporkan event perangkat yang didefinisikan dalam TSL perangkat.
 *
 * 
 * dev_handle: pengidentifikasi unik perangkat di Link IoT Edge.
 * event_name: nama event.
 * data: array parameter event @leda_device_data_t.
 * data_count: panjang array parameter event.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 *
 */
int leda_report_event(device_handle_t dev_handle, const char *event_name, const leda_device_data_t data[], int data_count);

/*
 * Memutus koneksi perangkat. Jika perangkat mengalami kerusakan atau sebelum Anda mematikan perangkat, Anda mungkin ingin memutus koneksi perangkat tersebut terlebih dahulu. Setelah perangkat diputus, Link IoT Edge tidak akan lagi meneruskan pesan ke perangkat tersebut.
 *
 * dev_handle: pengidentifikasi unik perangkat di Link IoT Edge.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 *
 */
int leda_offline(device_handle_t dev_handle);

/*
 * Menghubungkan perangkat ke IoT Platform. Perangkat hanya dapat dikenali oleh Link IoT Edge setelah terhubung ke IoT Platform.
 *
 * dev_handle: pengidentifikasi unik perangkat di Link IoT Edge.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
int leda_online(device_handle_t dev_handle);

/*
 * Menggunakan device_name yang telah dibuat di Alibaba Cloud IoT Platform untuk mendaftarkan, mengaktifkan, dan menghasilkan pengidentifikasi unik untuk perangkat.
 *
 * Jika Anda ingin mendaftarkan beberapa perangkat, Anda dapat memanggil fungsi ini beberapa kali.
 *
 * product_key: ProductKey produk yang dibuat di Alibaba Cloud IoT Platform.
 * device_name: Nama perangkat (DeviceName) yang dibuat di Alibaba Cloud IoT Platform.
 * device_cb: struktur callback perangkat. Untuk informasi lebih lanjut, lihat @leda_device_callback.
 * @usr_data: data pribadi yang ditentukan pengguna saat perangkat didaftarkan. Data ini dikirim ke perangkat selama callback.
 *
 * Fungsi blocking. Pengidentifikasi unik perangkat di Link IoT Edge dikembalikan. Nilai 0 menunjukkan bahwa perangkat valid, sedangkan nilai kurang dari 0 menunjukkan bahwa perangkat tidak valid.
 *
 */
device_handle_t leda_register_and_online_by_device_name(const char *product_key, const char *device_name, leda_device_callback_t *device_cb, void *usr_data);

/*
 * Menggunakan device_name kustom lokal untuk mendaftarkan, mengaktifkan, dan menghasilkan pengidentifikasi unik untuk perangkat.
 *
 * Jika Anda ingin mendaftarkan beberapa perangkat, Anda dapat memanggil fungsi ini beberapa kali.
 *
 * product_key: ProductKey produk yang dibuat di Alibaba Cloud IoT Platform.
 * local_name: nama perangkat. Nama perangkat dalam satu produk harus unik.
 * device_cb: struktur callback perangkat. Untuk informasi lebih lanjut, lihat @leda_device_callback.
 * @usr_data: data pribadi yang ditentukan pengguna saat perangkat didaftarkan. Data ini dikirim ke perangkat selama callback.
 *
 * Fungsi blocking. Pengidentifikasi unik perangkat di Link IoT Edge dikembalikan. Nilai 0 menunjukkan bahwa perangkat valid, sedangkan nilai kurang dari 0 menunjukkan bahwa perangkat tidak valid.
 *
 * Catatan: Anda tidak dapat menggunakan fungsi ini dan fungsi leda_register_and_online_by_device_name secara bersamaan. 
 * Semua perangkat dengan ProductKey yang sama harus menggunakan fungsi yang sama untuk pendaftaran perangkat. Jika tidak, pendaftaran dapat menghasilkan error.
 */
device_handle_t leda_register_and_online_by_local_name(const char *product_key, const char *local_name, leda_device_callback_t *device_cb, void *usr_data);

/*
 * Menginisialisasi modul driver. Selama inisialisasi, kolam thread pekerja dibuat dalam modul untuk memproses permintaan operasi perangkat dari IoT Platform secara asinkron. Anda dapat menetapkan jumlah thread pekerja dengan menentukan parameter worker_thread_nums.
 *
 * worker_thread_nums: jumlah thread dalam kolam thread. Nilai ini ditetapkan berdasarkan jumlah perangkat yang terdaftar.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
int leda_init(int worker_thread_nums);

/*
 * Menghentikan modul driver.
 *
 * Sebelum modul keluar, sumber daya dilepaskan.
 *
 * Fungsi blocking.
 */
void leda_exit(void);

/*
 * Mendapatkan panjang informasi driver.
 *
 * Fungsi blocking. Jika panjang informasi driver berhasil diperoleh, LE_SUCCESS dikembalikan. Jika permintaan gagal, 0 dikembalikan.
 */
int leda_get_driver_info_size(void);

/*
 * Mendapatkan informasi driver yang dikonfigurasi di IoT Platform.
 *
 * driver_info: informasi driver. Anda harus mengalokasikan memori terlebih dahulu.
 * size: panjang informasi driver. Jika ukuran driver_info lebih besar daripada parameter size, LE_ERROR_INVAILD_PARAM dikembalikan.
 *  
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 * 
 * Format konfigurasi:
    {
        "json":{
            "ip":"127.0.0.1",
            "port":54321
        },
        "kv":[
            {
                "key":"ip",
                "value":"127.0.0.1",
                "note":"IP address"
            },
            {
                "key":"port",
                "value":"54321",
                "note":"Port number"
            }
        ],
        "fileList":[
            {
                "path":"device_config.json"
            }
        ]
    }
 */
int leda_get_driver_info(char *driver_info, int size);

/*
 * Mendapatkan panjang informasi perangkat.
 *
 * Fungsi blocking. Jika panjang informasi perangkat berhasil diperoleh, LE_SUCCESS dikembalikan. Jika permintaan gagal, 0 dikembalikan.
 */
int leda_get_device_info_size(void);

/*
 * Mendapatkan informasi perangkat yang dikonfigurasi di IoT Platform.
 *
 * driver_info: informasi perangkat. Anda harus mengalokasikan memori terlebih dahulu.
 * size: panjang informasi perangkat. Anda dapat memperoleh panjang ini dengan memanggil metode leda_get_device_info_size. Jika ukuran device_info lebih besar daripada parameter size, LE_ERROR_INVAILD_PARAM dikembalikan.
 *  
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 * 
 * Format konfigurasi:
    [
        {
            "custom":{
                "port":12345,
                "ip":"127.0.0.1"
            },
            "deviceName":"device1",
            "productKey":"a1ccxxeypky"
        }
    ]
 */
int leda_get_device_info(char *device_info, int size);

/*
 * Mendapatkan panjang informasi konfigurasi driver.
 *
 * Fungsi blocking. Jika panjang konfigurasi driver berhasil diperoleh, LE_SUCCESS dikembalikan. Jika permintaan gagal, 0 dikembalikan.
 */
int leda_get_config_size(void);

/*
 * Mendapatkan semua konfigurasi driver.
 *
 * config: konfigurasi driver. Anda harus mengalokasikan memori terlebih dahulu.
 * size: panjang informasi perangkat. Anda dapat memperoleh panjang ini dengan memanggil metode leda_get_config_size. Jika ukuran device_info lebih besar daripada parameter size, LE_ERROR_INVAILD_PARAM dikembalikan.
 *  
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 * 
 * Format konfigurasi:
    {
        "config":{
            "json":{
                "ip":"127.0.0.1",
                "port":54321
            },
            "kv":[
                {
                    "key":"ip",
                    "value":"127.0.0.1",
                    "note":"IP address"
                },
                {
                    "key":"port",
                    "value":"54321",
                    "note":"Port number"
                }
            ],
            "fileList":[
                {
                    "path":"device_config.json"
                }
            ]
        },
        "deviceList":[
            {
                "custom":"{"port":12345,"ip":"127.0.0.1"}",
                "deviceName":"device1",
                "productKey":"a1ccxxeypky"
            }
        ]
    }
 */
int leda_get_config(char *config, int size);

/*
 * Metode callback yang digunakan untuk memodifikasi konfigurasi driver.
 *
 * config: informasi konfigurasi.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
typedef int (*config_changed_callback)(const char *config);

/*
 * Mengonfigurasi listener perubahan konfigurasi berbasis subscription untuk callback.
 *
 * config_cb: fungsi callback yang digunakan untuk memberi tahu perubahan konfigurasi.
 *
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
int leda_register_config_changed_callback(config_changed_callback config_cb);

/*
 * Mendapatkan panjang TSL berdasarkan ProductKey.
 *
 * product_key: ProductKey produk.
 *
 * Fungsi blocking. Jika panjang TSL berhasil diperoleh, LE_SUCCESS dikembalikan. Jika permintaan gagal, 0 dikembalikan.
 */
int leda_get_tsl_size(const char *product_key);

/*
 * Mendapatkan informasi TSL suatu produk berdasarkan ProductKey.
 *
 * product_key: ProductKey produk.
 * tsl: konten model TSL. Anda perlu mengalokasikan sumber daya memori terlebih dahulu untuk mengunggah data.
 * size: ukuran konten TSL. Anda dapat memperoleh ukuran ini dengan memanggil metode leda_get_tsl_size. Jika ukuran parameter tsl lebih besar daripada parameter size, LE_ERROR_INVAILD_PARAM dikembalikan.
 *  
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
int leda_get_tsl(const char *product_key, char *tsl, int size);

/*
 * Mendapatkan panjang informasi TSL ekstensi suatu produk berdasarkan ProductKey.
 *
 * product_key: ProductKey produk.
 *
 * Fungsi blocking. Jika permintaan berhasil, panjang informasi TSL ekstensi dikembalikan. Jika permintaan gagal, 0 dikembalikan.
 */
int leda_get_tsl_ext_info_size(const char *product_key);

/*
 * Mendapatkan informasi TSL ekstensi suatu produk berdasarkan ProductKey.
 *
 * product_key: ProductKey produk.
 * tsl_ext_info: informasi TSL ekstensi. Anda perlu mengalokasikan memori terlebih dahulu.
 * size: panjang informasi TSL ekstensi. Anda dapat memperoleh panjang ini dengan memanggil metode leda_get_tsl_ext_info_size. Jika ukuran device_info lebih besar daripada parameter size, LE_ERROR_INVAILD_PARAM dikembalikan.
 *  
 * Fungsi blocking. Jika permintaan berhasil, LE_SUCCESS dikembalikan. Jika permintaan gagal, kode kesalahan dikembalikan.
 */
int leda_get_tsl_ext_info(const char *product_key, char *tsl_ext_info, int size);

/*
 * Mendapatkan handle perangkat.
 *
 * product_key: ProductKey produk.
 * device_name: Nama perangkat (DeviceName).
 *
 * Fungsi blocking. Jika permintaan berhasil, handle perangkat dikembalikan. Jika permintaan gagal, angka kurang dari 0 dikembalikan.
 */
device_handle_t leda_get_device_handle(const char *product_key, const char *device_name);