Blue Print Data Provider Specification
Author : weLees
Contents and compilations published on this website by the providers are subject to international copyright laws. Reproduction, editing, distribution as well as the use of any kind outside the scope of the copyright law require written permission of the author or weLees.
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 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 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 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 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