data_provider_specification.txt

BLUE PRINT DATA PROVIDER SPECIFICATION


1. VERSION
  Version 1.0, 2021-11-18, WeLees Co.,Ltd.


2. LICENSE

COPYRIGHT 2021 WELEES. ALL RIGHTS RESERVED.
REDISTRIBUTION AND USE IN SOURCE AND BINARY FORMS, WITH OR WITHOUT MODIFICATION, ARE PERMITTED PROVIDED THAT THE FOLLOWING CONDITIONS ARE MET:
REDISTRIBUTIONS OF SOURCE CODE MUST RETAIN THE ABOVE COPYRIGHT NOTICE, THIS LIST OF CONDITIONS AND THE FOLLOWING DISCLAIMER.
REDISTRIBUTIONS OF SOURCE CODE AND BINARY FORMS FOR COMMERCIAL PURPOSES IS FORBIDDEN.
REDISTRIBUTIONS IN BINARY FORM MUST REPRODUCE THE ABOVE COPYRIGHT NOTICE, THIS LIST OF CONDITIONS AND THE FOLLOWING DISCLAIMER IN THE DOCUMENTATION AND/OR OTHER MATERIALS PROVIDED WITH THE DISTRIBUTION.
NEITHER THE NAME OF THE WELEES NOR THE NAMES OF ITS CONTRIBUTORS MAY BE USED TO ENDORSE OR PROMOTE PRODUCTS DERIVED FROM THIS SOFTWARE WITHOUT SPECIFIC PRIOR WRITTEN PERMISSION.


3. OVERVIEW

Blue Print is an intelligent cross-platform remote hexadecimal editor/analyzer developed by weLees. The data provider of the Blue Print uses an open protocol. If the built-in data provider of the Blue Print cannot meet users' requirements, users can develop their own data providers based on this protocol. Blue Prints are available in 32-bit and 64-bit systems. The architecture of the data provider must be the same as the software.


4. TERM

  4.1. Data Provider

    The data provider is a data providing module for Blue Prints. Blue Prints can access specific objects or files through the data provider. Blue Prints come with three data providers. The disk provider, file provider and volume provider. The data provider of the Blue Print uses an open frame. Any data provider compiled according to the data collection protocol can be used by the Blue Print. Users can refer to the Blue Print bringing data provider source code (download link: https://github.com/welees/Blue Print/tree/main/Projects/Provider) and develop their own data provider to access this specification.


5. TYPE DEFINITION

  BOOL
    typedef int BOOL;

  BOOLEAN
    typedef char BOOLEAN;

  CHAR,PCHAR
    typedef char CHAR,*PCHAR;

  UINT16,PUINT16
    typedef unsigned short UINT16,*PUINT16;

  UINT8,PUINT8
    typedef unsigned char UINT8,*PUINT8;

  UINT32,PUINT32,UINT,PUINT,ULONG,PULONG
    typedef unsigned int UINT32,*PUINT32,UINT,*PUINT,ULONG,*PULONG;

  CAUTION : Users should try to avoid UINT/ULONG type, it is recommended to use for any integer data as UINT8/UINT16/UINT32/UINT64 in order to make clear the variable size.

  UINT64,PUINT64
    typedef unsigned long long UINT64,*PUINT64;

  INT64,PINT64
    typedef long long INT64,*PINT64;

  PVOID
    typedef void *PVOID;


6. EXPORT FUNCTIONS

  extern "C" UINT32 ServiceEntry(IN UINT16 uCommand, IN PVOID pParameter)

  The data provider service entry function, which is invoked for all requirements.


7. COMMANDS & STRUCTURES DEFINITION

  7.1. Handshake Command

    After the Blue Print is started, the system searches for available data providers in ./proivders/. This command is invoked to establish contact with the data provider after the data provider is found.

    Command Code Definition
    #define _COMMAND_SHAKE_HAND 0
    
	Parameters Definition
      Input parameter : structure SHAKE_HAND
      Output parameter : structure SHAKE_HAND

      typedef struct _SHAKE_HAND
      {
          UINT16 MajorVersion, MinorVersion;
            Input : The version of Blue Print. The data provider uses these 2 members to know what features the Blue Print can provided.
            Output : The version of data provider.

          UINT32 Features;
            Input : None
            Output : 0

          UINT16 Type;
            Input : None
            Output : The type of the data provider, which is a combination of the following definitions:

            _PROVIDER_TYPE_SOLID_DEVICE_PROVIDER 1        The data of object generated by provider is solid
            _PROVIDER_TYPE_VIOLATILE_DEVICE_PROVIDER 2    The data of object generated by provider is volatile

          CHAR Name[32];
            Input : None
            Output : The name of the data provider, such as "Disk Provider"

          CHAR Description[256];
            Input : None
            Output : Description of the provider

          CHAR Vendor[256];
            Input : None
            Output : provider manufacturer name

      }SHAKE_HAND,*PSHAKE_HAND;


  7.2. Enumerate Device Command

    Blue Print invoke this command when the user clicks a provider on provider menu to enumerate the names of accessible devices.

    Command Code Definition
    #define _COMMAND_ENUM_DEVICE 1
    
	Parameters Definition
      Input parameter : Structure ENUM_DEVICE
      Output parameter : Structure ENUM_DEVICE

      Object information return by provider
      typedef struct _DEVICE_NAME
      {
          char Name[256];
            Input : None
            Output : Object name

          char Desc[1024];
            Input : None
            Output : Object description, including dimensions and other information

          BOOLEAN Folder;
            Input : None
            Output : TRUE if it is a directory, and vice versa

      }DEVICE_NAME,*PDEVICE_NAME;

      typedef struct _ENUM_DEVICE
      {
          CHAR Path[1024];
            Input : The path to enumerate, or "/" if it is the root directory. This parameter should be invalidate if the member Handle was not 0.
            Output : None

          UINT64 Handle;
            Input : Handle to enumerate. This parameter must be 0 for enumerating a new directory.
            Output : Enumerating handle of the current directory. The Blue Print will continue enumerating the remaining objects using the returned handle as an argument when enumerating later. When directory enumeration is complete (that is, when ReturnCount is less than RequestCount), the data provider should close the handle, and if user want to enumerate the current directory again later, who need to reset member Handle to 0 and specify the full path of the directory in the path parameter.

          UINT16 RequestCount;
            Input : The number of requested objects. The maximum number of returned objects cannot exceed this number.
            Output : None.

          UINT16 ReturnCount;
            Input : None
            Output : The number of objects returned. If the number returned is less than the requested number, it means enumerating operation of current directory is complete, the data provider should cleanup resource for enumerating.

          DEVICE_NAME Result[1];
            Input : None
            Output : Enumerated object list.

      }ENUM_DEVICE,*PENUM_DEVICE;


  7.3. Get Device Profile Command

    Blue Print invoke this command when the user clicks a provider to enumerate the names of accessible devices.

    Command Code Definition
    #define _COMMAND_GET_DEVICE_PROFILE 2
    
	Parameters Definition
      Input parameter : structure QUERY_DEVICE_PROFILE
      Output parameter : structure QUERY_DEVICE_PROFILE

      typedef struct _QUERY_DEVICE_PROFILE
      {
          char Name[1024];
            Input : Object full path name
            Output : None

          UINT64 TotalBytes;
            Input : None
            Output : Total bytes of the device

          UINT32 BlockSize;
            Input : None
            Output : total blocks of the device

          UINT32 Features;
            Input : None
            Output : Features supported by the object, a combination of the following values

            _DEVICE_FEATURE_BLOCK_DEVICE 1        The object is a block device
            _DEVICE_FEATURE_RESIZABLE 2           Object sizes can be changed (support insert/delete operation)
            _DEVICE_FEATURE_READ_ONLY 4           The object cannot be modified
            _DEVICE_FEATURE_VOLATILE 8            Object data is volatile
            _DEVICE_FEATURE_SEARCH 16             Search operations are supported for object

          char Description[1024];
            Input : None
            Output : Object description

          char InitializeParameters[4096];
            Input : None
            Output : Object initial parameter, a JSON string like "{Features:'0a',SectorSize:'200',TotalSectors:'7FFc00'}". Note that all values in the initial parameters must be hexadecimal.

      }QUERY_DEVICE_PROFILE,*PQUERY_DEVICE_PROFILE;


  7.4. Read/Write Command

    Read/write objects are consistent in their parameters and therefore put together.

    Command Code Definition
    #define _COMMAND_READ 3
    #define _COMMAND_WRITE 4

    Parameters Definition
      Input parameter : structure ACCESS_PARAM
      Output parameter : structure ACCESS_PARAM

      typedef struct _ACCESS_PARAM
      {
          char Name[1024];
            Input : Full path name of the object to be accessed
            Output : None

          UINT64 ByteOffset;
            Input : Byte offset of the object to be accessed
            Output : None

          PUINT8 Buffer;
            Input : Buffer that holds data written to the object
            Output : Buffer to hold data read from object

          UINT32 Size;
            Input : Number of bytes to read or write
            Output : None

      }ACCESS_PARAM,*PACCESS_PARAM;


  7.5. Data Search Command

    Blue Print invokes this command to perform data searching operation.

    Command Code Definition
    #define _COMMAND_SEARCH 5

    Parameters Definition
      Input parameter : structure SEARCH_PARAM
      Output parameter : structure SEARCH_RESULT

      Matched entry information
      typedef struct _SEARCH_ITEM
      {
          UINT64 BlockOffset;
            Input : None
            Output : The byte offset of block with matched data

          vector<UINT> CaseOffsetInBlock;
            Input : None
            Output : List of  offset in block of match entries in the current block whose value is the byte offset in the block

          PUINT8 BlockData;
            Input : None
            Output : Complete data for the corresponding block

      }SEARCH_ITEM,*PSEARCH_ITEM;

      typedef struct _SEARCH_RESULT
      {
          UINT64 CurrentOffset;
            Input : None
            Output : The offset currently being searched

          UINT32 ErrorCode;
            Input : None
            Output : 0 if there is None error, otherwise the error code

          UINT16 TaskID;
            Input : None
            Output : The data provider should assign an ID to each search task and return it to the Blue Print for farward operations

          UINT8 Status;
            Input : None
            Output : The status of the current searching task, as a combination of the following values

            _SEARCH_STATUS_STOPPED 1 The searching has be stopped
            _SEARCH_STATUS_STOPPING 2 The searching task is been stopping

          UINT8 MatchedCount;
            Input : None
            Output : Number of matches found since the search started/last query

          vector<SEARCH_ITEM> MatchItems;
            Input : None
            Output : match entries since the searching was started/last query

          LONG Lock; A lock for data provider. This definition is only available on Windows platforms
          
		  pthread_spinlock_t Lock; A lock for data provider. This definition is only available on Linux platforms
          
		  pthread_mutex_t Lock; A lock for data provider. This definition is only available on the MACOS platform

      }SEARCH_RESULT,*PSEARCH_RESULT;

      typedef struct _SEARCH_PARAM
      {
          vector<char> DeviceName;
            Input : Full path name of the object to be accessed
            Output : None

          UINT16 Features;
            Input : Specifies the characteristics of the searching task, as a combination of the following values
            Output : None

            _SEARCH_FEATURE_IGNORE_CASE 1         Search for an ASCII character string, ignoring case
            _SEARCH_FEATURE_SPECIFIED_POSITION 2  Matches only the specified offset in the object block
            _SEARCH_FEATURE_SPECIFIED_SECTION 4   Searches only the specified interval in the object block
            _SEARCH_FEATURE_REG_FORMAT 8          Regular expression searching

          UINT64 StartOffset,LastOffset;
            Input : Specifies the range to search for in the object
            Output : None

          UINT32 BlockSize;
            Input : Bytes of block with _SEARCH_FEATURE_SPECIFIED_XXX
            Output : None

          UINT32 OffsetInBlock;
            Input : Perform the in-block offset for _SEARCH_FEATURE_SPECIFIED_XXX search (the current version only supports search from this offset to the end of the block for _SEARCH_FEATURE_SPECIFIED_SECTION)
            Output : None

          UINT16 DataSize;
            Input : Characteristic data string length
            Output : None

          UINT16 TaskID;
            Input : ID of the searching task. For a new searching task, the value should be 0. If the value is not 0, it means query data from in-working task, and all members except Result are ignored.
            Output : None

          vector<UINT8> Data;
            Input : Characteristic data string
            Output : None

          PSEARCH_RESULT Result;
            Input : Buffer to receive search results
            Output : None

      }SEARCH_PARAM,*PSEARCH_PARAM;


  7.6. Clear Search Result Command

    Clears result information of specified searching task.

    Command Code Definition
    #define _COMMAND_CLEAR_SEARCH_RESULT 6

    Parameters Definition
      Input parameter : PUINT16 points to the task ID buffer
      Output parameter : None


  7.7. Stop Search Task Command

    Closes the specified searching task, terminates the searching thread, and releases resources.

    Command Code Definition
    #define _COMMAND_CLOSE_SEARCH_TASK 7

    Parameters Definition
      Input parameter : PUINT16 points to the task ID buffer
      Output parameter : None


  7.8. Replace Modified File Command (for Resizable objects only)

    When the Blue Print edits the file object (Resizable), it creates a temporary file for the modification. After writing to the temporary file, the Blue Print will rename the original file to .bak and then rename the temporary file to the user file.

    Command Code Definition
    #define _COMMAND_REPLACE_MODIFIED_FILE 8

    Parameters Definition
      Input parameter : structure REPLACE_MODIFIED_FILE
      Output parameter : None

      typedef struct _REPLACE_MODIFIED_FILE
      {
          char FileName[1024];
            Input : Full path object name to be modified
            Output : None

      }REPLACE_MODIFIED_FILE,*PREPLACE_MODIFIED_FILE;


  7.9. Service Stop

    This command is invoked when the blueprint is shut down. After receiving this command, the collector should save temporary data and release occupied resources for closing.

    Command Code Definition
    #define _COMMAND_STOP_SERVER 9

    Parameters Definition
      Input parameter : None
      Output parameters: None