Setup SDK

Windows SDK Integration Guide

Overview

• This guide is for developers who want to monetize Windows applications with PacketSDK.

• Integrating the PacketSDK into an application is the first step toward earning revenue. Once you've integrated the SDK, you will start seeing devices data and revenue in PacketSDK Dashboard in 24 hours.

• This document will walk you through the steps needed to be taken in order to properly integrate PacketSDK into your application.

Windows SDK Integration Guide

• Prerequisites

  • Step 1: Apply for appkey.

  • Step 2: Download integration package.

  • Step 3: Choose an integration method that suits you.

• Binary Executable Program Integration

  • Step 1: Find the binary executable program in the windows integration package.

  • Step 2: Launch executable program using appkey.

  • Step 3: Verify if integration is successful.

• .NET(C#) Integration

  • Step 1: Find the files required for C# integration in the windows integration package.

  • Step 2: Add references and import types contained in the namespace.

  • Step 3: Call related API in your code.

  • Step 4: Verify if integration is successful.

• C/C++ / Other Languages Integration

  • Step 1: Select the appropriate machine word length and link type.

  • Step 2: Add the required resources to your project based on the parameters you have selected.

  • Step 3: Call the relevant api in your app's code.

  • Step 4: Verify if integration is successful.

• API documentation

  • .NET (C#)

  • C/C++ API

Prerequisites

Step 1: Apply for appkey.

• Register and log in to the PacketSDK, go to Dashboard to create your app and get your appkey.

• 'appkey' is an important way to track your earnings, please ensure it is set correctly in the subsequent integration steps.

Step 2: Download integration package.

• Download the PacketSDK Windows integration package packet_sdk_win-1.0.*.zip and unzip it.

• Once you unzip the package, you can see the following contents: packet_sdk_win-1.0.*.zip ├─── bin - Pre compiled binary executable program. ├─── C#(.NET) - Dynamic libraries required for C#(.net) integration. ├─── C++(MSVC&MT) - 32 bits or 64 bits dynamic and static libraries required for C++ or other languages integration. └─── demos - C#, C++, Python and GoLang integration demos.

Step 3: Choose an integration method that suits you.

• Binary executable program integration

• .NET(C#) native integration

• C/C++ / Other programming language integration

Binary Executable Program Integration

Step 1: Find the binary executable program in the windows integration package.

• Copy packet_sdk.exe from the bin folder of integration package to your project.

Step 2: Launch executable program using appkey.

Supports two startup methods, starting with a regular executable program and starting with Windows services. The binary executable program packet_sdk.exe will automatically recognize it.

• Regular executable program(as an independent process or subprocesss):

  D:\packet_sdk.exe -appkey=test

• Windows services:

  # Create a Windows service and specify the program path.
  sc create PacketSDK binPath="D:\packet_sdk.exe -appkey=test"
  
  # Set the service to start automatically upon startup.
  sc config PacketSDK start= AUTO
  
  # Start service.
  net start PacketSDK
  
  # Stop service.
  net stop PacketSDK
  
  # Delete service.
  sc delete PacketSDK

Step 3: Verify if integration is successful.

• The log will be output in standard output by default, you can add startup parameters -logfile=enable to enable local log file recording in step 2. After activation, the log file will be created in the same level directory of the program, and the old logs will be overwritten after each restart of the program.

  D:\packet_sdk.exe -appkey=test -logfile=enable

• After step 2, if you receive Server information obtained successfully. Connection established successfully. and This device has been successfully certified. in the log, it indicates that you have successfully integrated Packet SDK.

• Once you've received This device has been successfully certified. in the log, you will start seeing devices data and revenue in Packet SDK Dashboard in 24 hours.

.NET(C#) Integration

Step 1: Find the files required for C# integration in the windows integration package.

• Copy PacketSDK.dll and PacketSDK.xml from the C#(.NET) directory to your project.

  Note

  • PacketSDK.xml is used for Visual Studio to automatically fill in intelligent perception information and document descriptions, and it is not a runtime dependency.

  • PacketSDK.dll is a runtime dependency that needs to be distributed in the same directory as the executable file.

  • Targeting .NET Framework 4.5 / 9.0 (AnyCPU)

Step 2: Add references and import types contained in the namespace.

• Add PacketSDK.dll as a reference to your project.

• Import "PacketSDKAPI" namespace in your code.

using PacketSDKAPI;

Step 3: Call related API in your code.

• Refer to the .NET API documentation at the bottom of this guide and directly call the relevant API.

• See integration code example below and refer to csharp_wpf_anycpu or csharp_winform_anycpu integration example in demos directory.

using PacketSDKAPI;
class YourAPP{
  static void onPacketSDKCallBack(packet_status_t status){
    Console.WriteLine("Packet SDK async callback with status: {0}", PacketSDK.StatusToStrng(status));
  }

  static void Main(string[] args){
    try{
      PacketSDK.SetCallBack(onPacketSDKCallBack);
      packet_status_t status =  PacketSDK.SetAppKey("appkey");
      if(packet_status_t.PACKET_SUCCESS != status){
        Console.WriteLine("Set Packet SDK appKey failed! Reason: {0}", PacketSDK.StatusToStrng(status));
      }
      else{
          PacketSDK.Start();
      }
    }
      catch (Exception ex){
      Console.WriteLine("Exception occurred: ",ex.Message);
    }
  }
}

Step 4: Verify if integration is successful.

• After call PacketSDK.Start() API, if you receive PACKET_SDK_SERVER_OBTAINED PACKET_SDK_SERVER_CONNECTED and PACKET_SDK_SERVER_CERTIFIED in the callback function you set, it indicates that you have successfully integrated Packet SDK into your application.

• Once you've received PACKET_SDK_SERVER_CERTIFIED in the callback function, you will start seeing devices data and revenue in Packet SDK Dashboard in 24 hours.

C/C++ / Other Languages Integration

Step 1: Select the appropriate machine word length and link type.

• Machine word length

  • 32 bits

  • 64 bits

• MSVC (Microsoft Visual C++ Compiler) Runtime

  • Since version 1.0.4, the MSVC runtime used by PacketSDK built in C++ only uses MT.

• Link Type

Note

• When using static links, static libraries will be inserted into your program.

• When using dynamic linking, you should distribute packet_sdk.dll along with your executable program.

• If your app is not developed in C++ language, or your C++ compiler is not MSVC, the link type can only be selected as Run time Dynamic Linking.

Step 2: Add the required resources to your project based on the parameters you have selected.

• Static Link （MSVC C/C++）

  • Copy header file packet_sdk.h from the C++(MSVC&MT) directory to your project.

  • Copy static library packet_sdk_static.lib from C++(MSVC&MT)/win32(win64)/static_link directory to your project.

  • Add the header file(packet_sdk.h) to your project and define the macro "PACKET_SDK_STATIC_LINK" in header file.

  • Inform the build system to link static library to executable program.

    • Visual Studio: Enter "PATH" in "Project - Attribute - Configure Properties - VC++ directory - Library directory". Enter "packet_sdk_static.lib" in "Project - Attribute - Configure Properties - Linker - Input - Additional dependencies".

    • Preprocessor directives: #pragma comment(lib, "/PATH/packet_sdk_static.lib")

    • cmake: link_directories(${PATH})

      target_link_libraries(${PROJECT_NAME} "packet_sdk_static.lib" )

    • qmake(.pro): LIBS += -l/PATH/packet_sdk_static

    Note

    • You can choose one of the methods to inform the build system based on the actual situation.

    • You should replace "PATH" with the actual path of the static library packet_sdk_static.lib.

• Load-time Dynamic Linking （MSVC C/C++）

  • Copy header file packet_sdk.h from the C++(MSVC&MT) directory to your project.

  • Copy export library packet_sdk.lib from MSVC/win32(win64)/dynamic_link directory to your project.

  • Add the header file(.h) to your project and define the macro "PACKET_SDK_DYNAMIC_LINK" in header file.

  • Inform the build system to link export library to executable program.

    • Visual Studio: Enter "LIBPATH" in "Project - Attribute - Configure Properties - VC++ directory - Library directory". Enter "packet_sdk.lib" in "Project - Attribute - Configure Properties - Linker - Input - Additional dependencies".

    • Preprocessor directives: #pragma comment(lib, "/LIBPATH/packet_sdk.lib")

    • cmake: link_directories(${LIBPATH})

      target_link_libraries(${PROJECT_NAME} "packet_sdk.lib")

    • qmake:LIBS += -l/LIBPATH/packet_sdk

    Note

    • You can choose one of the methods to inform the build system based on the actual situation.

    • You should replace "PATH" with the actual path of the export library packet_sdk.lib.

  • When distributing the app, packet_sdk.dll needs to be distributed together, and its location should be in the same level directory as the executable program.

• Run-time Dynamic Linking (C++ MinGW Compiler / Other Languages)

  • When distributing the app, packet_sdk.dll needs to be distributed together, and its location should be in the same level directory as the executable program.

Step 3: Call the relevant api in your app's code.

• Static Link (MSVC C/C++)

  • Refer to the C++ API documentation at the bottom of this guide and directly call the relevant API declaration in the header file.

  • See integration code example below and refer to vc++_console_64bit in demos directory.

// *****************************          Static Link (MSVC C/C++)         *************************************
#include <iostream>
#include <thread>  
#include <chrono> 

// Include Packet SDK header file and define the macro "PACKET_SDK_STATIC_LINK" in the header file "packet_sdk.h" .
#include "../../C++(MSVC&MT)/packet_sdk.h"

// Using pre-processing instructions to notify the construction of system linked Packet SDK static library.
#pragma comment(lib, "../../C++(MSVC&MT)/win64/static_link/packet_sdk_static.lib") 

class Program {
public:
  static void PacketCallBack(int status) {
    std::cout << "Packet SDK callback with status: " << status << " Message: " << packet_strstatus(status) << std::endl;
  }
};

int main(){
  packet_sdk_set_callBack(Program::PacketCallBack);

  int status = packet_sdk_set_appKey("appkey");
  if (status) {
    std::cout << status << "Set applicaiton key failed! Message: " << packet_strstatus(status);
    return -1;
  }

  status = packet_sdk_start();
  if (status) {
    std::cout << "Launch Packet SDK failed! Message: " << packet_strstatus(status);
    return -1;
  }

  while (1) {
    std::this_thread::sleep_for(std::chrono::seconds(5));
    std::cout << "Stimulate your application.\n";
  }
}

• Load-time Dynamic Linking (MSVC C/C++)

  • Refer to the C++ API documentation at the bottom of this guide and directly call the relevant API declaration in the header file.

  • See integration code example below and refer to qt_widget_32bit or qt_qml_32bit in demos directory.

// *****************************   Load-time Dynamic Linking (MSVC C/C++)  *************************************
#include <iostream>
#include <thread>  
#include <chrono> 

// Include Packet SDK header file and define the macro "PACKET_SDK_DYNAMIC_LINK" in the header file "packet_sdk.h" .
#include "../../C++(MSVC&MT)/packet_sdk.h"

// Using pre-processing instructions to notify the construction of system linked PacketSDK export library.
#pragma comment(lib, "../../C++(MSVC&MT)/win64/static_link/packet_sdk.lib") 

class Program {
public:
  static void onPacketCallBack(int status) {
      std::cout << "Packet SDK callback with status: " << status << " Message: " << packet_strstatus(status) << std::endl;
  }
};

int main(){
  packet_sdk_set_callBack(Program::onPacketCallBack);

  int status = packet_sdk_set_appKey("appkey");
  if (status) {
      std::cout << status << "Set applicaiton key failed! Message: " << packet_strstatus(status);
      return -1;
  }

  status = packet_sdk_start();
  if (status) {
      std::cout << "Launch Packet SDK failed! Message: " << packet_strstatus(status);
      return -1;
  }

  while (1) {
      std::this_thread::sleep_for(std::chrono::seconds(5));
      std::cout << "Simulate the UI event loop of your app.\n";
  }
}

• Run-time Dynamic Linking (C++ MinGW Complier / Other Programming Languages)

  • Load dynamic libraries based on your programming language.

  • Parse symbols based on function signature based on your programming language.

  • Call the function according to the C++ API documentation below.

// **************   Run-time Dynamic Linking (C++ MinGW Complier)  **************
#include <stdio.h>  		// #include <iostream> 
#include <windows.h>  

// (1) Load library
HMODULE hMod = LoadLibrary(TEXT("packet_sdk.dll"));
if (NULL == hMod) {  
  printf("Load Packet SDK failed. Error: %d\n", GetLastError());  
}  

// (2) Parsing symbols (Taking packet_sdk_set_appKey API as an example)
typedef int (*packetSDKSetAppKeyFuncType)(const char*);
packetSDKSetAppKeyFuncType setAppKeyFunc = (packetSDKSetAppKeyFuncType)GetProcAddress(hMod, "packet_sdk_set_appKey");
if (setAppKeyFunc) {  
  printf("Obtain function address successful.\n"); 
}else{
  printf("Failed to obtain function address. Error: %d\n", GetLastError());  	
  FreeLibrary(hMod); 
}

// Parsing symbols (packet_sdk_start)
  ......

// (3) Calling API packet_sdk_set_appKey and packet_sdk_start
  int status = setAppKeyFunc("appkey");
  ......


// **************   Run-time Dynamic Linking (Other languages)  **************
  // Code based on your actual programming language.
  // Refer to the example in the demos folder.

Step 4: Verify if integration is successful.

• After call packet_sdk_start() API, if receive PACKET_SDK_SERVER_OBTAINED PACKET_SDK_SERVER_CONNECTED and PACKET_SDK_SERVER_CERTIFIED in the callback function you set, it indicates that you have successfully integrated Packet SDK into your application.

• Once you've received PACKET_SDK_SERVER_CERTIFIED in the callback function, you will start seeing devices data and revenue in Packet SDK Dashboard in 24 hours.

API documentation

• API functions marked with [**Required**] are essential for integration, while other APIs are optional.

• Setting the appkey should be done before starting the SDK call.

• Once the callback function is successfully set, your callback function will immediately receive a PACKET_CLLACK_STSUCCESS

.NET (C#)

// Packet SDK callback function signature.
delegate void CallBackDelegate(packet_status_t status);

// Set callback function to receive Packet SDK asynchronous status.
static void SetCallBack(CallBackDelegate callBackFunc);

// Cancel the callback of Packet SDK.
static void UnSetCallBack();

// [**Required**] Set application key for Packet SDK.
static packet_status_t SetAppKey(string appkey);

// [**Required**] Start Packet SDK.
static packet_status_t Start();

// Stop Packet SDK.
static packet_status_t Stop();

// Querying the current status.
static packet_status_t QueryServerStatus();

// Convert status to readable strings.
static string StatusToString(packet_status_t status);

enum packet_status_t{
  PACKET_SUCCESS,                 // Operation successful.

  PACKET_CALLBACK_SETSUCCESS,     // Callback function setting successful.

  PACKET_APPKEY_UNSET,            // Application key not set.
  PACKET_APPKEY_INVALID,          // Invalid application key.
  PACKET_APPKEY_DUPLICATESETTING, // Application key duplicate setting.

  PACKET_SDK_NOT_RUNNING,         // The Packet SDK is currently not in a startup state.
  PACKET_SDK_RUNNING,             // Packet SDK is already in startup state.

  PACKET_SDK_SERVER_OBTAINED,     // Server information obtained.
  PACKET_SDK_SERVER_CONNECTED,    // Connection has been established with the server.
  PACKET_SDK_SERVER_CERTIFIED,    // Certification successful.
  PACKET_SDK_SERVER_DISCONNECTED, // Disconnect from server.
}

C/C++ API

// Returns the version of PacketSDK as a string.
const char* packet_sdk_version();

// PacketSDK callback function signature.
typedef void (*packet_sdk_callback_t)(int);

// Set callback function to receive PacketSDK asynchronous callback status_code. 
void packet_sdk_set_callBack(CallbackFunc callBack);

// Cancel callback.
void packet_sdk_unset_callBack();

// [**Required**] Set application key for PacketSDK.
int packet_sdk_set_appKey(char* appkey);

// [**Required**] Start PacketSDK in a new thread automatically, the current thread will not block.
int packet_sdk_start();

// Stop SDK.
int packet_sdk_stop();

// Querying the current PackerSDK status.
int packet_sdk_queryServerStatus();

// Convert status_code to readable strings.
const char* packet_strstatus(int status_code);

typedef enum packet_status_t {
  PACKET_SUCCESS,                 // Operation successful.
  PACKET_CALLBACK_SETSUCCESS,     // Callback function setting successful.

  PACKET_APPKEY_UNSET,            // Application key not set.
  PACKET_APPKEY_INVALID,          // Application key invalid.
  PACKET_APPKEY_DUPLICATESETTING, // Application key duplicate setting.

  PACKET_SDK_NOT_RUNNING,         // The Packet SDK is currently not in a startup state.
  PACKET_SDK_RUNNING,             // Packet SDK is already in startup state.

  PACKET_SDK_SERVER_OBTAINED,     // Server information obtained.
  PACKET_SDK_SERVER_CONNECTED,    // Connection has been established with the server.
  PACKET_SDK_SERVER_CERTIFIED,    // Certification successful.
  PACKET_SDK_SERVER_DISCONNECTED, // Disconnect from server.
} packet_status_t;