# Module Service - Data ## Overview The Data Service provides general-purpose distributed data storage and management within the Cellframe SDK. This service offers comprehensive data handling capabilities including storage, retrieval, replication, and access control for various data types across the Cellframe network infrastructure. *Based on: `dap_chain_net_srv_data.h`, `dap_chain_net_srv_data.c`* ## Document Structure - [[#Overview|Overview]] - [[#Data Structures|Data Structures]] - [[#Data Item Structure|Data Item Structure - Storage unit]] - [[#Storage Context|Storage Context - Storage management]] - [[#Data Functions|Data Functions]] - [[#Storage Management|Storage Management Functions]] - [[#Data Operations|Data Operations Functions]] - [[#Typical Examples|Typical Examples]] ## Data Structures ### Data Item Structure Structure representing a stored data item. ```c typedef struct dap_chain_net_srv_data_item { dap_chain_hash_fast_t hash; // Content hash (content-addressed) char name[128]; // Data item name char content_type[64]; // MIME content type uint64_t size; // Data size in bytes uint64_t created_timestamp; // Creation timestamp uint64_t modified_timestamp; // Last modification timestamp dap_chain_addr_t owner_addr; // Owner address uint32_t access_flags; // Access control flags uint32_t replication_factor; // Number of replicas void *data_ptr; // Pointer to actual data bool is_encrypted; // Encryption status } dap_chain_net_srv_data_item_t; ``` ### Storage Context Structure Structure for managing storage operations and context. ```c typedef struct dap_chain_net_srv_data_context { dap_chain_net_t *net; // Network context char storage_path[256]; // Local storage path uint64_t total_capacity; // Total storage capacity uint64_t used_capacity; // Currently used storage uint32_t active_items; // Number of active data items pthread_mutex_t storage_mutex; // Thread-safe storage access dap_chain_net_srv_data_item_t *items; // Hash table of stored items } dap_chain_net_srv_data_context_t; ``` ### Data Query Structure Structure for data search and retrieval operations. ```c typedef struct dap_chain_net_srv_data_query { char name_pattern[128]; // Name search pattern char content_type_filter[64]; // Content type filter dap_chain_addr_t owner_filter; // Owner address filter uint64_t min_size; // Minimum size filter uint64_t max_size; // Maximum size filter uint64_t created_after; // Created after timestamp uint64_t created_before; // Created before timestamp uint32_t max_results; // Maximum results to return } dap_chain_net_srv_data_query_t; ``` ### Access Control Flags Flags for data access control. ```c #define DAP_DATA_ACCESS_READ 0x01 // Read permission #define DAP_DATA_ACCESS_WRITE 0x02 // Write permission #define DAP_DATA_ACCESS_DELETE 0x04 // Delete permission #define DAP_DATA_ACCESS_PUBLIC 0x08 // Public access #define DAP_DATA_ACCESS_ENCRYPTED 0x10 // Encrypted storage #define DAP_DATA_ACCESS_IMMUTABLE 0x20 // Immutable data ``` ## Data Functions ### Storage Management #### `dap_chain_net_srv_data_init()` Initializes the data service. ```c int dap_chain_net_srv_data_init(dap_config_t *a_config); ``` **Parameters:** - `a_config` (dap_config_t *) - Configuration context **Returns:** - `0` - Initialization successful - Non-zero - Initialization failed #### `dap_chain_net_srv_data_deinit()` Deinitializes the data service. ```c void dap_chain_net_srv_data_deinit(); ``` #### `dap_chain_net_srv_data_create_context()` Creates a data storage context. ```c dap_chain_net_srv_data_context_t* dap_chain_net_srv_data_create_context( dap_chain_net_t *a_net, const char *a_storage_path, uint64_t a_capacity ); ``` **Parameters:** - `a_net` (dap_chain_net_t *) - Network context - `a_storage_path` (const char *) - Local storage directory path - `a_capacity` (uint64_t) - Storage capacity in bytes **Returns:** - Pointer to storage context - `NULL` if creation failed #### `dap_chain_net_srv_data_destroy_context()` Destroys a data storage context. ```c void dap_chain_net_srv_data_destroy_context(dap_chain_net_srv_data_context_t *a_context); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Context to destroy ### Data Operations #### `dap_chain_net_srv_data_store()` Stores data in the distributed storage system. ```c int dap_chain_net_srv_data_store( dap_chain_net_srv_data_context_t *a_context, const char *a_name, const char *a_content_type, const void *a_data, size_t a_data_size, dap_chain_addr_t *a_owner_addr, uint32_t a_access_flags ); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Storage context - `a_name` (const char *) - Data item name - `a_content_type` (const char *) - MIME content type - `a_data` (const void *) - Data to store - `a_data_size` (size_t) - Size of data - `a_owner_addr` (dap_chain_addr_t *) - Owner address - `a_access_flags` (uint32_t) - Access control flags **Returns:** - `0` - Storage successful - `-1` - Invalid parameters - `-2` - Insufficient storage capacity - `-3` - Storage failed #### `dap_chain_net_srv_data_retrieve()` Retrieves data from storage. ```c dap_chain_net_srv_data_item_t* dap_chain_net_srv_data_retrieve( dap_chain_net_srv_data_context_t *a_context, const char *a_name, dap_chain_addr_t *a_requester_addr ); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Storage context - `a_name` (const char *) - Data item name - `a_requester_addr` (dap_chain_addr_t *) - Requester address for access control **Returns:** - Pointer to data item - `NULL` if not found or access denied #### `dap_chain_net_srv_data_retrieve_by_hash()` Retrieves data by content hash. ```c dap_chain_net_srv_data_item_t* dap_chain_net_srv_data_retrieve_by_hash( dap_chain_net_srv_data_context_t *a_context, dap_chain_hash_fast_t *a_hash, dap_chain_addr_t *a_requester_addr ); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Storage context - `a_hash` (dap_chain_hash_fast_t *) - Content hash - `a_requester_addr` (dap_chain_addr_t *) - Requester address **Returns:** - Pointer to data item - `NULL` if not found or access denied #### `dap_chain_net_srv_data_delete()` Deletes data from storage. ```c int dap_chain_net_srv_data_delete( dap_chain_net_srv_data_context_t *a_context, const char *a_name, dap_chain_addr_t *a_requester_addr ); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Storage context - `a_name` (const char *) - Data item name - `a_requester_addr` (dap_chain_addr_t *) - Requester address **Returns:** - `0` - Deletion successful - `-1` - Data not found - `-2` - Access denied - `-3` - Deletion failed #### `dap_chain_net_srv_data_search()` Searches for data items based on query criteria. ```c dap_chain_net_srv_data_item_t** dap_chain_net_srv_data_search( dap_chain_net_srv_data_context_t *a_context, dap_chain_net_srv_data_query_t *a_query, uint32_t *a_result_count ); ``` **Parameters:** - `a_context` (dap_chain_net_srv_data_context_t *) - Storage context - `a_query` (dap_chain_net_srv_data_query_t *) - Search query - `a_result_count` (uint32_t *) - Output result count **Returns:** - Array of data item pointers - `NULL` if no results found #### `dap_chain_net_srv_data_verify_integrity()` Verifies data integrity using content hash. ```c bool dap_chain_net_srv_data_verify_integrity(dap_chain_net_srv_data_item_t *a_item); ``` **Parameters:** - `a_item` (dap_chain_net_srv_data_item_t *) - Data item to verify **Returns:** - `true` - Data integrity verified - `false` - Data corruption detected ## Typical Examples ### Data Storage and Retrieval Example ```c #include <dap_chain_net_srv_data.h> void data_storage_example() { log_it_info("=== Data Storage and Retrieval Example ==="); // Step 1: Initialize data service dap_config_t *config = dap_config_default(); int init_result = dap_chain_net_srv_data_init(config); if (init_result != 0) { log_it_error("✗ Data service initialization failed: %d", init_result); return; } log_it_info("✓ Data service initialized successfully"); // Step 2: Setup network and storage context dap_chain_net_t *net = dap_chain_net_by_name("backbone"); if (!net) { log_it_error("✗ Network 'backbone' not found"); return; } const char *storage_path = "/tmp/cellframe_data_storage"; uint64_t storage_capacity = 1024 * 1024 * 1024; // 1GB capacity dap_chain_net_srv_data_context_t *storage_context = dap_chain_net_srv_data_create_context( net, storage_path, storage_capacity ); if (!storage_context) { log_it_error("✗ Failed to create storage context"); return; } log_it_info("✓ Storage context created successfully"); log_it_info(" Path: %s", storage_path); log_it_info(" Capacity: %.1f MB", storage_capacity / (1024.0 * 1024.0)); // Step 3: Prepare owner address dap_chain_addr_t owner_addr; if (dap_chain_addr_from_str(&owner_addr, "mJWQjJA4iXQ7HCZkZHgmPFNv9xAA7GV9eMUTjRdBGNBuKVaZZ3qw2k") != 0) { log_it_error("✗ Invalid owner address format"); dap_chain_net_srv_data_destroy_context(storage_context); return; } // Step 4: Store different types of data log_it_info("--- Data Storage Operations ---"); // Store text data const char *text_data = "Hello, Cellframe! This is a test document."; int store_result1 = dap_chain_net_srv_data_store( storage_context, "test_document.txt", "text/plain", text_data, strlen(text_data), &owner_addr, DAP_DATA_ACCESS_READ | DAP_DATA_ACCESS_PUBLIC ); if (store_result1 == 0) { log_it_info("✓ Text document stored successfully"); } else { log_it_error("✗ Text document storage failed: %d", store_result1); } // Store JSON data const char *json_data = "{\"name\":\"Alice\",\"age\":30,\"city\":\"New York\"}"; int store_result2 = dap_chain_net_srv_data_store( storage_context, "user_profile.json", "application/json", json_data, strlen(json_data), &owner_addr, DAP_DATA_ACCESS_READ | DAP_DATA_ACCESS_WRITE ); if (store_result2 == 0) { log_it_info("✓ JSON data stored successfully"); } else { log_it_error("✗ JSON data storage failed: %d", store_result2); } // Store binary data (simulated) uint8_t binary_data[256]; for (int i = 0; i < 256; i++) { binary_data[i] = (uint8_t)i; } int store_result3 = dap_chain_net_srv_data_store( storage_context, "binary_file.bin", "application/octet-stream", binary_data, sizeof(binary_data), &owner_addr, DAP_DATA_ACCESS_READ | DAP_DATA_ACCESS_ENCRYPTED ); if (store_result3 == 0) { log_it_info("✓ Binary data stored successfully"); } else { log_it_error("✗ Binary data storage failed: %d", store_result3); } // Step 5: Retrieve stored data log_it_info("--- Data Retrieval Operations ---"); dap_chain_net_srv_data_item_t *retrieved_text = dap_chain_net_srv_data_retrieve( storage_context, "test_document.txt", &owner_addr ); if (retrieved_text) { log_it_info("✓ Text document retrieved successfully"); log_it_info(" Name: %s", retrieved_text->name); log_it_info(" Content Type: %s", retrieved_text->content_type); log_it_info(" Size: %lu bytes", retrieved_text->size); log_it_info(" Created: %lu", retrieved_text->created_timestamp); log_it_info(" Encrypted: %s", retrieved_text->is_encrypted ? "Yes" : "No"); // Verify data integrity bool integrity_ok = dap_chain_net_srv_data_verify_integrity(retrieved_text); log_it_info(" Integrity: %s", integrity_ok ? "Verified" : "CORRUPTED"); } else { log_it_error("✗ Text document retrieval failed"); } // Step 6: Display storage statistics log_it_info("--- Storage Statistics ---"); log_it_info("Storage Context Information:"); log_it_info(" Total Capacity: %.1f MB", storage_context->total_capacity / (1024.0 * 1024.0)); log_it_info(" Used Capacity: %.1f MB", storage_context->used_capacity / (1024.0 * 1024.0)); log_it_info(" Available: %.1f MB", (storage_context->total_capacity - storage_context->used_capacity) / (1024.0 * 1024.0)); log_it_info(" Active Items: %u", storage_context->active_items); log_it_info(" Usage: %.2f%%", (double)storage_context->used_capacity / storage_context->total_capacity * 100.0); // Step 7: Cleanup dap_chain_net_srv_data_destroy_context(storage_context); log_it_info("✓ Storage context destroyed"); log_it_info("Data storage and retrieval example completed"); } ``` ### Data Search and Management Example ```c #include <dap_chain_net_srv_data.h> void data_search_example() { log_it_info("=== Data Search and Management Example ==="); // Step 1: Setup storage context (assuming already initialized) dap_chain_net_t *net = dap_chain_net_by_name("backbone"); if (!net) { log_it_error("✗ Network not found"); return; } dap_chain_net_srv_data_context_t *storage_context = dap_chain_net_srv_data_create_context( net, "/tmp/cellframe_search_test", 1024 * 1024 * 1024 ); if (!storage_context) { log_it_error("✗ Failed to create storage context"); return; } // Step 2: Setup search query log_it_info("--- Data Search Operations ---"); dap_chain_net_srv_data_query_t search_query = {0}; strcpy(search_query.name_pattern, "*.json"); // Search for JSON files strcpy(search_query.content_type_filter, "application/json"); search_query.min_size = 0; search_query.max_size = 1024 * 1024; // Max 1MB search_query.max_results = 10; log_it_info("Search Query:"); log_it_info(" Name Pattern: %s", search_query.name_pattern); log_it_info(" Content Type: %s", search_query.content_type_filter); log_it_info(" Size Range: %lu - %lu bytes", search_query.min_size, search_query.max_size); log_it_info(" Max Results: %u", search_query.max_results); // Step 3: Execute search uint32_t result_count = 0; dap_chain_net_srv_data_item_t **search_results = dap_chain_net_srv_data_search( storage_context, &search_query, &result_count ); if (search_results && result_count > 0) { log_it_info("✓ Search completed successfully"); log_it_info(" Results found: %u", result_count); log_it_info("Search Results:"); log_it_info("╭──────────────────────────────────────────────────────────────────╮"); log_it_info("│ Name │ Size │ Content Type │ Created │"); log_it_info("├──────────────────────────────────────────────────────────────────┤"); for (uint32_t i = 0; i < result_count; i++) { dap_chain_net_srv_data_item_t *item = search_results[i]; char size_str[16]; if (item->size < 1024) { snprintf(size_str, sizeof(size_str), "%lu B", item->size); } else if (item->size < 1024 * 1024) { snprintf(size_str, sizeof(size_str), "%.1f KB", item->size / 1024.0); } else { snprintf(size_str, sizeof(size_str), "%.1f MB", item->size / (1024.0 * 1024.0)); } log_it_info("│ %-19s │ %-8s │ %-17s │ %-11lu │", item->name, size_str, item->content_type, item->created_timestamp); } log_it_info("╰──────────────────────────────────────────────────────────────────╯"); // Step 4: Access control demonstration log_it_info("--- Access Control Check ---"); for (uint32_t i = 0; i < result_count && i < 3; i++) { dap_chain_net_srv_data_item_t *item = search_results[i]; log_it_info("Item '%s' access flags:", item->name); if (item->access_flags & DAP_DATA_ACCESS_READ) { log_it_info(" • Read: Allowed"); } if (item->access_flags & DAP_DATA_ACCESS_WRITE) { log_it_info(" • Write: Allowed"); } if (item->access_flags & DAP_DATA_ACCESS_DELETE) { log_it_info(" • Delete: Allowed"); } if (item->access_flags & DAP_DATA_ACCESS_PUBLIC) { log_it_info(" • Public: Yes"); } if (item->access_flags & DAP_DATA_ACCESS_ENCRYPTED) { log_it_info(" • Encrypted: Yes"); } if (item->access_flags & DAP_DATA_ACCESS_IMMUTABLE) { log_it_info(" • Immutable: Yes"); } } // Free search results free(search_results); } else { log_it_info("No results found matching search criteria"); } // Step 5: Content-addressed retrieval by hash log_it_info("--- Hash-based Retrieval ---"); log_it_info("Content-addressed storage allows retrieval by hash:"); // Example hash (would be actual content hash in real implementation) dap_chain_hash_fast_t example_hash; memset(&example_hash, 0x42, sizeof(dap_chain_hash_fast_t)); dap_chain_addr_t requester_addr; dap_chain_addr_from_str(&requester_addr, "mJWQjJA4iXQ7HCZkZHgmPFNv9xAA7GV9eMUTjRdBGNBuKVaZZ3qw2k"); dap_chain_net_srv_data_item_t *hash_item = dap_chain_net_srv_data_retrieve_by_hash( storage_context, &example_hash, &requester_addr ); if (hash_item) { log_it_info("✓ Data retrieved by hash successfully"); } else { log_it_info("Data not found for given hash (expected for this example)"); } // Step 6: Cleanup dap_chain_net_srv_data_destroy_context(storage_context); log_it_info("Data search and management example completed"); } ``` --- *See also: [[Modules/Module Service|Module Service]], [[Modules/Module Service - Mining Pool|Module Service - Mining Pool]], [[ETC/Services Overview|Services Overview]]*