00001 ////////////////////////////////////////////////////////////////////////////// 00002 // hwapi.h - Hex Workshop API 00003 // 00004 // This source code and information is provided "as is" without any warranty 00005 // of any kind, either expressed or implied, including but not limited to 00006 // the implied waranties of merchantability and/or fitness for a particular 00007 // purpose. 00008 // 00009 // Copyright (c) 2010 BreakPoint Software, Inc. All Rights Reserved. 00010 // 00011 ////////////////////////////////////////////////////////////////////////////// 00012 // 00013 //// 00014 00015 #ifndef _HWAPI_H 00016 #define _HWAPI_H /* [ */ 00017 00018 #include "hwapierr.h" 00019 00020 #ifdef HWAPI_EXPORTS 00021 # define HWAPI extern "C" __declspec(dllexport) 00022 # define HWAPIEP 00023 #else 00024 # define HWAPI extern "C" __declspec(dllimport) 00025 # define HWAPIEP extern "C" __declspec(dllexport) 00026 #endif 00027 00028 /** 00029 * @brief Hex Workshop Document Handle 00030 * @ingroup common 00031 * 00032 * A HWDOCUMENT handle represents an open document within Hex Workshop. 00033 * Plug-ins are provided a HWDOCUMENT during Plug-in execution or Plug-ins 00034 * receive document handles by calling hwOpenDocument or hwNewDocument. 00035 * 00036 * Handles should not be stored or re-used across plug-in executions. 00037 */ 00038 typedef HANDLE HWDOCUMENT ; 00039 00040 /** 00041 * @brief Hex Workshop Plug-in Session Handle 00042 * @ingroup common 00043 * 00044 * HWSESSION handles are provided to the plug-in during execution and 00045 * represent a plug-in execution session. 00046 * 00047 * Handles should not be stored or re-used across plug-in executions. 00048 */ 00049 typedef HANDLE HWSESSION ; 00050 00051 /** 00052 * @brief signed 64 bit integer 00053 * @ingroup common 00054 */ 00055 typedef __int64 QWORD ; 00056 00057 /** 00058 * @brief Signed/unsigned indicator 00059 * @ingroup common 00060 */ 00061 typedef enum 00062 { 00063 HWAPI_SIGN_SIGNED = 0, /**< @brief signed value */ 00064 HWAPI_SIGN_UNSIGNED = 1 /**< @brief unsigned value */ 00065 } HWAPI_SIGN ; 00066 00067 00068 /** 00069 * @brief Byte Order indicator 00070 * @ingroup common 00071 */ 00072 typedef enum 00073 { 00074 HWAPI_BYTEORDER_BIG_ENDIAN = 0, /**< @brief Big Endian (MSB) */ 00075 HWAPI_BYTEORDER_LITTLE_ENDIAN = 1 /**< @brief Little Endian (LSB) */ 00076 } HWAPI_BYTEORDER ; 00077 00078 00079 /** @name Open, Close, Save APIs */ 00080 00081 /** 00082 * @brief Open an existing document 00083 * @ingroup document 00084 * 00085 * @param hSession [IN] Hex Workshop Plug-in session handle 00086 * @param lpstrFile [IN] Path to file 00087 * @param bReadOnly [IN] TRUE to open read-only, FALSE for write access 00088 * 00089 * @return NULL if unable to open a file or a non-NULL value on success 00090 */ 00091 HWAPI HWDOCUMENT hwOpenDocument(HWSESSION hSession, 00092 LPCTSTR lpstrFile, 00093 BOOL bReadOnly) ; 00094 00095 /** 00096 * @brief Create a new empty document 00097 * @ingroup document 00098 * 00099 * @param hSession [IN] Hex Workshop Plug-in session handle 00100 * 00101 * @return NULL on error or a non-NULL value on success 00102 */ 00103 HWAPI HWDOCUMENT hwNewDocument(HWSESSION hSession) ; 00104 00105 /** 00106 * @brief Save document 00107 * @ingroup document 00108 * 00109 * @note Use hwSaveDocumentAs for document created using hwNewDocument 00110 * 00111 * @param hDocument [IN] Hex Workshop document handle 00112 * 00113 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00114 * codes 00115 */ 00116 HWAPI HWAPI_RESULT hwSaveDocument(HWDOCUMENT hDocument) ; 00117 00118 /** 00119 * @brief Save Document as under the specified file name. 00120 * @ingroup document 00121 * 00122 * @note If the file exists, the user is prompted to overwrite. 00123 * 00124 * @param hDocument [IN] Hex Workshop document handle 00125 * @param szFileName [IN] Full path to destination file 00126 * 00127 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00128 * codes 00129 */ 00130 HWAPI HWAPI_RESULT hwSaveDocumentAs(HWDOCUMENT hDocument, 00131 LPCTSTR szFileName) ; 00132 00133 /** 00134 * @brief Close the specified document 00135 * @ingroup document 00136 * 00137 * @param hDocument [IN] Hex Workshop document handle 00138 * 00139 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00140 * codes 00141 */ 00142 HWAPI HWAPI_RESULT hwCloseDocument(HWDOCUMENT hDocument) ; 00143 00144 /** @} */ 00145 /** @name Property APIs */ 00146 00147 /** 00148 * @brief Get document size 00149 * @ingroup document 00150 * 00151 * @param hDocument [IN] Hex Workshop document handle 00152 * @param pqwFileSize [OUT] Size of the document in bytes 00153 * 00154 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00155 * codes 00156 */ 00157 HWAPI HWAPI_RESULT hwGetDocumentSize(HWDOCUMENT hDocument, 00158 QWORD* pqwFileSize) ; 00159 00160 00161 /** 00162 * @brief Get the document filename 00163 * @ingroup document 00164 * 00165 * @param hDocument [IN] Hex Workshop document handle 00166 * @param lpstrFileName [OUT] Buffer to place filename 00167 * @param nFileName [IN] Size of the buffer in TCHARs 00168 * 00169 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00170 * codes 00171 */ 00172 HWAPI HWAPI_RESULT hwGetFileName(HWDOCUMENT hDocument, 00173 LPTSTR lpstrFileName, 00174 size_t nFileName) ; 00175 00176 /** 00177 * @brief Get the document read-only status 00178 * @ingroup document 00179 * 00180 * @param hDocument [IN] Hex Workshop document handle 00181 * @param pbReadOnly [OUT] TRUE if readonly otherwise FALSE 00182 * 00183 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00184 * codes 00185 */ 00186 HWAPI HWAPI_RESULT hwGetReadOnly(HWDOCUMENT hDocument, 00187 BOOL* pbReadOnly) ; 00188 00189 /** @} */ 00190 /** @name Data Manipulation APIs */ 00191 00192 /** 00193 * @brief Read a block a data at the specified offset 00194 * @ingroup document 00195 * 00196 * @param hDocument [IN] Hex Workshop document handle 00197 * @param qwOffset [IN] Starting offset location 00198 * @param vpBuffer [OUT] Data Buffer 00199 * @param qwLength [IN] Length of data buffer in bytes 00200 * 00201 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00202 * codes 00203 */ 00204 HWAPI HWAPI_RESULT hwReadAt(HWDOCUMENT hDocument, 00205 QWORD qwOffset, 00206 void* vpBuffer, 00207 QWORD qwLength) ; 00208 00209 /** 00210 * @brief Write a block of data starting at the specified offset 00211 * @ingroup document 00212 * 00213 * @note This operation will overwrite data in the document 00214 * 00215 * @param hDocument [IN] Hex Workshop document handle 00216 * @param qwOffset [IN] Starting offset location 00217 * @param vpBuffer [IN] Data Buffer 00218 * @param qwLength [IN] Length of data buffer in bytes 00219 * 00220 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00221 * codes 00222 */ 00223 HWAPI HWAPI_RESULT hwWriteAt(HWDOCUMENT hDocument, 00224 QWORD qwOffset, 00225 void* vpBuffer, 00226 QWORD qwLength) ; 00227 00228 00229 00230 /** 00231 * @brief Replace data at the specified offset 00232 * @ingroup document 00233 * 00234 * @param hDocument [IN] Hex Workshop document handle 00235 * @param qwOffset [IN] Starting offset location 00236 * @param vpBuffer [IN] Data Buffer 00237 * @param qwSrcLength [IN] Length of the data to replace in bytes (original data) 00238 * @param qwTrgLength [IN] Length of vpBuffer in bytes (target or new data) 00239 * 00240 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00241 * codes 00242 */ 00243 HWAPI HWAPI_RESULT hwReplaceAt(HWDOCUMENT hDocument, 00244 QWORD qwOffset, 00245 void* vpBuffer, 00246 QWORD qwSrcLength, 00247 QWORD qwTrgLength) ; 00248 00249 /** 00250 * @brief Insert data at the specified offset 00251 * @ingroup document 00252 * 00253 * @param hDocument [IN] Hex Workshop document handle 00254 * @param qwOffset [IN] Starting offset location 00255 * @param vpBuffer [IN] Data Buffer 00256 * @param qwLength [IN] Length of data buffer in bytes 00257 * 00258 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00259 * codes 00260 */ 00261 HWAPI HWAPI_RESULT hwInsertAt(HWDOCUMENT hDocument, 00262 QWORD qwOffset, 00263 void* vpBuffer, 00264 QWORD qwLength) ; 00265 00266 /** 00267 * @brief Delete data at the specified offset 00268 * @ingroup document 00269 * 00270 * @param hDocument [IN] Hex Workshop document handle 00271 * @param qwOffset [IN] Starting offset location 00272 * @param qwLength [IN] Length of data to delete in bytes 00273 * 00274 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00275 * codes 00276 */ 00277 HWAPI HWAPI_RESULT hwDeleteAt(HWDOCUMENT hDocument, 00278 QWORD qwOffset, 00279 QWORD qwLength) ; 00280 /** @} */ 00281 /** @name Undo Control APIs */ 00282 00283 /** 00284 * @brief Enable the Hex Workshop undo features 00285 * @ingroup document 00286 * 00287 * Enables the Hex Workshop undo feature. By default, undo is enabled, but 00288 * can be disabled by calling hwUndoDisable. 00289 * 00290 * @param hDocument [IN] Hex Workshop document handle 00291 * 00292 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00293 * codes 00294 */ 00295 HWAPI HWAPI_RESULT hwUndoEnable(HWDOCUMENT hDocument) ; 00296 00297 /** 00298 * @brief Disabled the Hex Workshop undo feature 00299 * @ingroup document 00300 * 00301 * Disables the Hex Workshop undo feature. Users may want to disable undo 00302 * when implementing import functions that include many operations. 00303 * 00304 * @param hDocument [IN] Hex Workshop document handle 00305 * 00306 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00307 * codes 00308 */ 00309 HWAPI HWAPI_RESULT hwUndoDisable(HWDOCUMENT hDocument) ; 00310 00311 /** 00312 * @brief Begin grouping undo operations 00313 * @ingroup document 00314 * 00315 * Groups multiple document changes into a single undo operation. Groups 00316 * cannot be nested -- calling this API twice, without calling hwUndoEndGroup 00317 * results in an error. 00318 * 00319 * @param hDocument [IN] Hex Workshop document handle 00320 * 00321 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00322 * codes 00323 */ 00324 HWAPI HWAPI_RESULT hwUndoBeginGroup(HWDOCUMENT hDocument) ; 00325 00326 /** 00327 * @brief Stop grouping undo operations 00328 * @ingroup document 00329 * 00330 * Stop grouping document changes into a single undo operation and commit the 00331 * undo group. 00332 * 00333 * @param hDocument [IN] Hex Workshop document handle 00334 * 00335 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00336 * codes 00337 */ 00338 HWAPI HWAPI_RESULT hwUndoEndGroup(HWDOCUMENT hDocument) ; 00339 00340 /** @} */ 00341 00342 /** 00343 * @brief Force the editor view to repaint 00344 * @ingroup editor 00345 * 00346 * Forces Hex Workshop to redraw the editor view with any changes. Hex 00347 * Workshop automatically refreshes the editor view at the end of a plug-in 00348 * execution. Redraws can be expensive and care should be used when calling. 00349 * 00350 * @param hDocument [IN] Hex Workshop document handle 00351 * 00352 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00353 * codes 00354 */ 00355 HWAPI HWAPI_RESULT hwRefreshView(HWDOCUMENT hDocument) ; 00356 00357 00358 /** 00359 * @brief Bookmark Data Types 00360 * @ingroup bookmarks 00361 * 00362 * @see HWAPI_BOOKMARK 00363 * @see hwBookmarksAdd 00364 * @see hwBookmarksGetAt 00365 */ 00366 typedef enum 00367 { 00368 HWAPI_DATATYPE_NONE = 0, /**< @brief No Data Type */ 00369 HWAPI_DATATYPE_BYTE = 1, /**< @brief 8-bit byte */ 00370 HWAPI_DATATYPE_WORD = 2, /**< @brief 16-bit word */ 00371 HWAPI_DATATYPE_DWORD = 3, /**< @brief 32-bit dword */ 00372 HWAPI_DATATYPE_QWORD = 4, /**< @brief 64-bit qword */ 00373 HWAPI_DATATYPE_FLOAT = 5, /**< @brief 32-bit float */ 00374 HWAPI_DATATYPE_DOUBLE = 6, /**< @brief 64 bit double */ 00375 HWAPI_DATATYPE_STRING = 7, /**< @brief ASCII string */ 00376 HWAPI_DATATYPE_UNICODE_STRING = 8, /**< @brief Unicode (wchar_t) string */ 00377 HWAPI_DATATYPE_MSDOSDate = 9, /**< @brief 16-bit MSDOS date format */ 00378 HWAPI_DATATYPE_MSDOSTime = 10, /**< @brief 16 bit MSDOS time format */ 00379 HWAPI_DATATYPE_FILETIME = 11, /**< @brief 64-bit FILETIME time/date format */ 00380 HWAPI_DATATYPE_UNIXTIME = 12, /**< @brief 32-bit time_t format */ 00381 HWAPI_DATATYPE_OLEDATETIME = 13, /**< @brief 64-bit OLEDATETIME format */ 00382 HWAPI_DATATYPE_STRUCTURE = 15, /**< @brief structure definition */ 00383 HWAPI_DATATYPE_BLOB = 19, /**< @brief 8-bit blob (unexpanded array) */ 00384 HWAPI_DATATYPE_UNIXTIME64 = 20, /**< @brief 64-bit time64_t format */ 00385 HWAPI_DATATYPE_CHAR = 22, /**< @brief 8-bit char */ 00386 HWAPI_DATATYPE_WCHAR = 23, /**< @brief 16-bit wchar_t */ 00387 HWAPI_DATATYPE_HALFFLOAT = 24 /**< @brief 16-bit half precision float (IEEE 754-2008) */ 00388 } HWAPI_DATATYPE ; 00389 00390 /** 00391 * @brief Bookmark definition 00392 * @ingroup bookmarks 00393 * 00394 * @note the cbSize must be set when getting and setting bookmarks 00395 * 00396 * @see hwBookmarksAdd 00397 * @see hwBookmarksGetAt 00398 * @see HWAPI_DATATYPE 00399 * @see HWAPI_SIGN 00400 * @see HWAPI_BYTEORDER 00401 * 00402 */ 00403 typedef struct 00404 { 00405 WORD cbSize ; /**< @brief Size of this structure in bytes */ 00406 QWORD qwAddress ; /**< @brief Bookmark Address */ 00407 DWORD dwArrayCount ; /**< @brief Number of elements */ 00408 HWAPI_DATATYPE eType ; /**< @brief Bookmark Type */ 00409 HWAPI_SIGN eSign ; /**< @brief Bookmark Sign */ 00410 HWAPI_BYTEORDER eByteOrder ; /**< @brief Bookmark Byte Order */ 00411 TCHAR cDescription[80] ; /**< @brief Bookmark Description */ 00412 TCHAR cStructureName[128] ; /**< @brief Bookmark Structure name */ 00413 } HWAPI_BOOKMARK ; 00414 00415 /** 00416 * @brief Bookmark Properties Definition 00417 * @ingroup bookmarks 00418 * 00419 * @note The cbSize must be set when getting and setting properties 00420 * @note If a file name is specified for cStructureLib instead of a full path, 00421 * Hex Workshop will attempt to load the structure library from the 00422 * default structure library directory. 00423 * 00424 * @see hwBookmarkCollectionGetProps 00425 * @see hwBookmarkCollectionSetProps 00426 */ 00427 typedef struct 00428 { 00429 WORD cbSize ; /**< @brief Size of this structure in bytes */ 00430 TCHAR cDescription[80] ; /**< @brief Collection Description */ 00431 TCHAR cAuthor[80] ; /**< @brief Collection Author */ 00432 TCHAR cStructureLib[256] ; /**< @brief Collection's assoicated structure library */ 00433 } HWAPI_BOOKMARK_COLLECTION_PROPS ; 00434 00435 /** 00436 * @brief Add a Bookmark 00437 * @ingroup bookmarks 00438 * 00439 * Adds a bookmark to a Hex Workshop Document. 00440 * 00441 * @param hDocument [IN] Hex Workshop document handle 00442 * @param pBookmark [IN] Pointer to a HWAPI_BOOKMARK containing the bookmark 00443 * definition 00444 * 00445 * @note The cbSize method must be initialized in the HWAPI_BOOKMARK 00446 * structure. 00447 * 00448 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00449 * codes 00450 */ 00451 HWAPI HWAPI_RESULT hwBookmarksAdd(HWDOCUMENT hDocument, 00452 HWAPI_BOOKMARK* pBookmark) ; 00453 00454 /** 00455 * @brief Get number of bookmarks 00456 * @ingroup bookmarks 00457 * 00458 * @param hDocument [IN] Hex Workshop document handle 00459 * @param pdwCount [OUT] Buffer to place bookmark count 00460 * 00461 * @note Bookmark arrays are expanded into multiple bookmarks entries. 00462 * 00463 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00464 * codes 00465 */ 00466 HWAPI HWAPI_RESULT hwBookmarksGetCount(HWDOCUMENT hDocument, 00467 DWORD* pdwCount) ; 00468 00469 /** 00470 * @brief Get bookmark at specified index 00471 * @ingroup bookmarks 00472 * 00473 * @param hDocument [IN] Hex Workshop document handle 00474 * @param dwIndex [IN] Bookmark index 00475 * @param pBookmark [OUT] Pointer to a HWAPI_BOOKMARK to be filled with 00476 * bookmark data. 00477 * 00478 * @note The cbSize method must be initialized in the HWAPI_BOOKMARK 00479 * structure. 00480 * 00481 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00482 * codes 00483 */ 00484 HWAPI HWAPI_RESULT hwBookmarksGetAt(HWDOCUMENT hDocument, 00485 DWORD dwIndex, 00486 HWAPI_BOOKMARK* pBookmark) ; 00487 00488 /** 00489 * @brief Remove bookmark at specified index 00490 * @ingroup bookmarks 00491 * 00492 * @param hDocument [IN] Hex Workshop document handle 00493 * @param dwIndex [IN] Bookmark index to remove 00494 * 00495 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00496 * codes 00497 */ 00498 HWAPI HWAPI_RESULT hwBookmarksRemoveAt(HWDOCUMENT hDocument, 00499 DWORD dwIndex) ; 00500 00501 /** 00502 * @brief Clear all bookmark entries 00503 * @ingroup bookmarks 00504 * 00505 * Clear all bookmark entries for the specified document. Bookmark Properties 00506 * are not modified. 00507 * 00508 * @param hDocument [IN] Hex Workshop document handle 00509 * 00510 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00511 * codes 00512 */ 00513 HWAPI HWAPI_RESULT hwBookmarksClear(HWDOCUMENT hDocument) ; 00514 00515 /** 00516 * @brief Load a bookmark collection 00517 * @ingroup bookmarks 00518 * 00519 * Loads a pre-existing bookmark collection from the file system. If a file 00520 * name is provided (not a full path), Hex Workshop will attempt to load the 00521 * bookmarks from the default Bookmark directory. 00522 * 00523 * @param hDocument [IN] Hex Workshop document handle 00524 * @param szBookmarkFile [IN] Bookmark file to load 00525 * 00526 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00527 * codes 00528 */ 00529 HWAPI HWAPI_RESULT hwBookmarkCollectionLoad(HWDOCUMENT hDocument, 00530 TCHAR* szBookmarkFile) ; 00531 00532 /** 00533 * @brief Save a bookmark collection 00534 * @ingroup bookmarks 00535 * 00536 * Save the bookmarks to disk. This operation will fail if the bookmark 00537 * collection has never been saved. For new bookmarks, please use 00538 * hwBookmarkCollectionSaveAs. 00539 * 00540 * @param hDocument [IN] Hex Workshop document handle 00541 * 00542 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00543 * codes 00544 */ 00545 HWAPI HWAPI_RESULT hwBookmarkCollectionSave(HWDOCUMENT hDocument) ; 00546 00547 /** 00548 * @brief Save bookmark collection as specified file 00549 * @ingroup bookmarks 00550 * 00551 * @param hDocument [IN] Hex Workshop document handle 00552 * @param szBookmarkFile [IN] Bookmark file to save collection as. If a file 00553 * name is provided (not a full path), Hex Workshop will attempt to save the 00554 * bookmarks in the default Bookmark directory. 00555 * 00556 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00557 * codes 00558 */ 00559 HWAPI HWAPI_RESULT hwBookmarkCollectionSaveAs(HWDOCUMENT hDocument, 00560 TCHAR* szBookmarkFile) ; 00561 00562 /** 00563 * @brief Get bookmark collection properties 00564 * @ingroup bookmarks 00565 * 00566 * Get the Bookmark collection properties (description, author, and associated 00567 * structure library). 00568 * 00569 * @param hDocument [IN] Hex Workshop document handle 00570 * @param pProps [IN] Bookmark collection properties 00571 * 00572 * @note The cbSize value must be initialized in the 00573 * HWAPI_BOOKMARK_COLLECTION_PROPS 00574 * 00575 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00576 * codes 00577 */ 00578 HWAPI HWAPI_RESULT hwBookmarkCollectionGetProps(HWDOCUMENT hDocument, 00579 HWAPI_BOOKMARK_COLLECTION_PROPS* pProps) ; 00580 00581 /** 00582 * @brief Set bookmark collection properties 00583 * @ingroup bookmarks 00584 * 00585 * Set the Bookmark collection properties (description, author, and associated 00586 * structure library). 00587 * 00588 * @param hDocument [IN] Hex Workshop document handle 00589 * @param pProps [OUT] Bookmark collection properties 00590 * 00591 * @note The cbSize value must be initialized in the 00592 * HWAPI_BOOKMARK_COLLECTION_PROPS 00593 * 00594 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00595 * codes 00596 */ 00597 HWAPI HWAPI_RESULT hwBookmarkCollectionSetProps(HWDOCUMENT hDocument, 00598 HWAPI_BOOKMARK_COLLECTION_PROPS* pProps) ; 00599 00600 00601 /** 00602 * @brief Load (or reload) the designated structure library. 00603 * @ingroup bookmarks 00604 * 00605 * Load the designated structure library. If the structure library is already 00606 * loaded, it will be reloaded (removing any structures added from this 00607 * library). The library is automatically set active. 00608 * 00609 * @param hSession [IN] Hex Workshop Plug-in session handle 00610 * @param lpstrFileName [IN] Filename or path to structure library. If only 00611 * a file name is provided (not a full path), Hex Workshop will 00612 * expand the path to match the default Structure directory. 00613 * 00614 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00615 * codes 00616 */ 00617 HWAPI HWAPI_RESULT hwStructureLibraryLoad(HWSESSION hSession, 00618 LPCTSTR lpstrFileName) ; 00619 00620 /** 00621 * @brief Close/Unload the specified structure library. 00622 * @ingroup structures 00623 * 00624 * Close/Unload the specified library and remove all structures added from 00625 * this library. 00626 * 00627 * @param hSession [IN] Hex Workshop Plug-in session handle 00628 * @param lpstrFileName [IN] Filename or path to structure library. If only 00629 * a file name is provided (not a full path), Hex Workshop will 00630 * expand the path to match the default Structure directory. 00631 * 00632 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00633 * codes 00634 */ 00635 HWAPI HWAPI_RESULT hwStructureLibraryClose(HWSESSION hSession, 00636 LPCTSTR lpstrFileName) ; 00637 00638 /** 00639 * @brief Set the active structure library 00640 * @ingroup structures 00641 * 00642 * Sets the active structure library. The hwStructureAddFloating, 00643 * hwStructureAddLocked, and hwStructureExecuteFunction APIs use the active 00644 * structure library (what is displayed in the Structure Viewer's dropdown 00645 * box) to lookup structure and function names. Other libraries are not 00646 * search. 00647 * 00648 * @param hSession [IN] Hex Workshop Plug-in session handle 00649 * @param lpstrFileName [IN] Filename or path to structure library. If only 00650 * a file name is provided (not a full path), Hex Workshop will 00651 * expand the path to match the default Structure directory. 00652 * 00653 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00654 * codes 00655 */ 00656 HWAPI HWAPI_RESULT hwStructureLibrarySetActive(HWSESSION hSession, 00657 LPCTSTR lpstrFileName) ; 00658 00659 /** 00660 * @brief Gets the active structure library. 00661 * @ingroup structures 00662 * 00663 * Gets the active structure library and returns the full file path in 00664 * lpstrFileName. 00665 * 00666 * @param hSession [IN] Hex Workshop Plug-in session handle 00667 * @param lpstrFileName [OUT] Buffer to place the active structure library. 00668 * The full path to the structure library is always returned. 00669 * @param nFileName [IN] The size of the lpstrFileName buffer in TCHARs. IF 00670 * the supplied buffer is too small, the API will return 00671 * HWAPI_RESULT_BUFFER_TOO_SMALL. 00672 * 00673 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00674 * codes 00675 */ 00676 HWAPI HWAPI_RESULT hwStructureLibraryGetActive(HWSESSION hSession, 00677 LPTSTR lpstrFileName, 00678 size_t nFileName) ; 00679 00680 /** 00681 * @brief Removes all structures displayed in the Structure Viewer. 00682 * @ingroup structures 00683 * 00684 * Removes locked and floating structures for all documents. 00685 * 00686 * @param hSession [IN] Hex Workshop Plug-in session handle 00687 * 00688 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00689 * codes 00690 */ 00691 HWAPI HWAPI_RESULT hwStructureRemoveAll(HWSESSION hSession) ; 00692 00693 /** 00694 * @brief Removes all structures locked to the designated document. 00695 * @ingroup structures 00696 * 00697 * Removes all structures locked to the designated document. Float structures 00698 * and structures locked to other documents are not removed. 00699 * 00700 * @param hDocument [IN] Hex Workshop document handle 00701 * 00702 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00703 * codes 00704 */ 00705 HWAPI HWAPI_RESULT hwStructureRemoveAllDocument(HWDOCUMENT hDocument) ; 00706 00707 /** 00708 * @brief Add a floating structure 00709 * @ingroup structures 00710 * 00711 * Adds a float structure to the structure viewer control within Hex Workshop. 00712 * Floating structures are not bound to a document or offset and are 00713 * re-evaluated on all document focus and caret position changes. 00714 * 00715 * @param hSession [IN] Hex Workshop Plug-in session handle 00716 * @param lpstrStructureName [IN] The name of the structure that should be 00717 * added. 00718 * @param byteOrder [IN] The desired byte order that should be used during 00719 * structure parsing/rendering. If the structure library declares 00720 * a byte order, that byte order is used and this parameter is 00721 * ignored. 00722 * 00723 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00724 * codes 00725 */ 00726 HWAPI HWAPI_RESULT hwStructureAddFloating(HWSESSION hSession, 00727 LPCTSTR lpstrStructureName, 00728 HWAPI_BYTEORDER byteOrder) ; 00729 00730 00731 /** 00732 * @brief Adds a locked structure 00733 * @ingroup structures 00734 * 00735 * Adds a structure to a document at a specific offset. The structure is 00736 * displayed in the structure viewer control within Hex Workshop. 00737 * 00738 * @param hDocument [IN] Hex Workshop document handle 00739 * @param lpstrStructureName [IN] The name of the structure that should be 00740 * added. 00741 * @param qwOffset [IN] The offset to place the locked structure. 00742 * @param byteOrder [IN] The desired byte order that should be used during 00743 * structure parsing/rendering. If the structure library declares 00744 * a byte order, that byte order is used and this parameter is 00745 * ignored. 00746 * 00747 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00748 * codes 00749 */ 00750 HWAPI HWAPI_RESULT hwStructureAddLocked(HWDOCUMENT hDocument, 00751 LPCTSTR lpstrStructureName, 00752 QWORD qwOffset, 00753 HWAPI_BYTEORDER byteOrder) ; 00754 00755 /** 00756 * @brief Execute a function within a structure library. 00757 * @ingroup structures 00758 * 00759 * @param hDocument [IN] Hex Workshop document handle 00760 * @param lpstrFunctionName [IN] The name of the function that should be 00761 * executed. 00762 * @param byteOrder [IN] The desired byte order that should be used during 00763 * function parsing/evaluation. If the structure library declares 00764 * a byte order, that byte order is used and this parameter is 00765 * ignored. 00766 * 00767 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00768 * codes 00769 */ 00770 HWAPI HWAPI_RESULT hwStructureExecuteFunction(HWDOCUMENT hDocument, 00771 LPCTSTR lpstrFunctionName, 00772 HWAPI_BYTEORDER byteOrder) ; 00773 00774 /** 00775 * @brief Hex Workshop Checksum Algorithm types 00776 * @ingroup checksums 00777 * 00778 * @note These algorithms are defined as bitmasks; however, plug-ins may only 00779 * define a single algorithm at a time. 00780 */ 00781 typedef enum 00782 { 00783 /** 1 byte: Simple count where all the bytes are added in an 8 bit accumulator. Initial value is 0. */ 00784 HWCSA_CHECKSUM8 = 0x00000001, 00785 /** 2 bytes: Simple count where all the bytes are added in an 16 bit accumulator. Initial value is 0. */ 00786 HWCSA_CHECKSUM16 = 0x00000002, 00787 /** 2 bytes: 16 bit Cyclic Redundancy Check (CRC) with a polynomial of 0x8005 and an initial value of 0x0000. */ 00788 HWCSA_CRC16 = 0x00000004, 00789 /** 2 bytes: 16 bit Cyclic Redundancy Check (CRC) with a polynomial of 0x1021 and an initial value of 0xFFFF. */ 00790 HWCSA_CRC16CCITT = 0x00000008, 00791 /** 4 bytes: 32 bit Cyclic Redundancy Check (CRC) with a polynomial of 0x04C11DB7 and an initial value of 0xFFFFFFFF. */ 00792 HWCSA_CRC32 = 0x00000010, 00793 /** 16 bytes: MD2 Message-Digest Algorithm (RSA Data Security, Inc.) */ 00794 HWCSA_MD2 = 0x00000020, 00795 /** 16 bytes: MD4 Message-Digest Algorithm (RSA Data Security, Inc.) */ 00796 HWCSA_MD4 = 0x00000040, 00797 /** 16 bytes: MD5 Message-Digest Algorithm (RSA Data Security, Inc.) */ 00798 HWCSA_MD5 = 0x00000080, 00799 /** 20 bytes: 160 bit Secure Hash Algorithm (NIST) */ 00800 HWCSA_SHA1 = 0x00000100, 00801 /** 4 bytes: Simple count where all the bytes are added in an 32 bit accumulator. Initial value is 0. */ 00802 HWCSA_CHECKSUM32 = 0x00000200, 00803 /** 8 bytes: Simple count where all the bytes are added in an 64 bit accumulator. Initial value is 0. */ 00804 HWCSA_CHECKSUM64 = 0x00000400, 00805 /** 2 bytes: 16 bit Cyclic Redundancy Check (CRC) with a user supplied polynomial and initial value. */ 00806 HWCSA_CUSTOM_CRC16 = 0x00000800, 00807 /** 28 bytes: 224 bit Secure Hash Algorithm (NIST) */ 00808 HWCSA_SHA224 = 0x00001000, 00809 /** 32 bytes: 256 bit Secure Hash Algorithm (NIST) */ 00810 HWCSA_SHA256 = 0x00002000, 00811 /** 48 bytes: 384 bit Secure Hash Algorithm (NIST) */ 00812 HWCSA_SHA384 = 0x00004000, 00813 /** 64 bytes: 512 bit Secure Hash Algorithm (NIST) */ 00814 HWCSA_SHA512 = 0x00008000, 00815 /** 16 bytes: 128 bit RACE Integrity Primitives Evaluation Message Digest (RIPEMD) */ 00816 HWCSA_RIPEMD128 = 0x00010000, 00817 /** 20 bytes: 160 bit RACE Integrity Primitives Evaluation Message Digest (RIPEMD) */ 00818 HWCSA_RIPEMD160 = 0x00020000, 00819 /** 32 bytes: 256 bit RACE Integrity Primitives Evaluation Message Digest (RIPEMD) */ 00820 HWCSA_RIPEMD256 = 0x00040000, 00821 /** 40 bytes: 320 bit RACE Integrity Primitives Evaluation Message Digest (RIPEMD) */ 00822 HWCSA_RIPEMD320 = 0x00080000, 00823 /** 24 bytes: 192 bit Tiger Digest Algorithm */ 00824 HWCSA_TIGER = 0x00100000, 00825 /** 64 bytes: 512 bit Whirlpool Hash Algorithm */ 00826 HWCSA_WHIRLPOOL = 0x00200000, 00827 /** 4 bytes: 32 bit Cyclic Redundancy Check (CRC) with a user supplied polynomial and initial value. */ 00828 HWCSA_CUSTOM_CRC32 = 0x00400000, 00829 } HW_CHECKSUM_ALGORITHM ; 00830 00831 /** @brief Custom CRC-16 parameters 00832 * @ingroup checksums 00833 * 00834 * @note Make sure to set the cbSize when supplying this structure 00835 */ 00836 typedef struct 00837 { 00838 DWORD cbSize ; /**< @brief size of structure in bytes */ 00839 WORD wPolynomial ; /**< @brief Polynomial value */ 00840 WORD wInitialValue ; /**< @brief Starting value */ 00841 BOOL bReflectIn ; /**< @brief Enable reflection of input bytes */ 00842 BOOL bReflectOut ; /**< @brief Enable reflect of output */ 00843 WORD wXOROut ; /**< @brief XOR with results */ 00844 } HW_CUSTOMCRC16INFO ; 00845 00846 /** @brief Custom CRC-32 parameters 00847 * @ingroup checksums 00848 * 00849 * @note Make sure to set the cbSize when supplying this structure 00850 */ 00851 typedef struct 00852 { 00853 DWORD cbSize ; /**< @brief size of structure in bytes */ 00854 DWORD dwPolynomial ; /**< @brief Polynomial value */ 00855 DWORD dwInitialValue ; /**< @brief Starting value */ 00856 BOOL bReflectIn ; /**< @brief Enable reflection of input bytes */ 00857 BOOL bReflectOut ; /**< @brief Enable reflect of output */ 00858 DWORD dwXOROut ; /**< @brief XOR with results */ 00859 } HW_CUSTOMCRC32INFO ; 00860 00861 00862 /** @brief Query result buffer size required for a check algorithm 00863 * @ingroup checksums 00864 * 00865 * @param hSession [IN] Hex Workshop Plug-in session handle 00866 * @param algorithm [IN] Algorithm type as defined by HW_CHECKSUM_ALGORITHM 00867 * @param pnLength [OUT] Checksum result size in bytes 00868 * 00869 * @see HW_CHECKSUM_ALGORITHM, hwChecksumDocument, hwChecksumBuffer 00870 * 00871 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00872 * codes 00873 */ 00874 HWAPI HWAPI_RESULT hwChecksumLength(HWSESSION hSession, 00875 HW_CHECKSUM_ALGORITHM algorithm, 00876 size_t* pnLength) ; 00877 00878 /** @brief Calculate a checksum for a document 00879 * @ingroup checksums 00880 * 00881 * @param hDocument [IN] Hex Workshop document handle 00882 * @param algorithm [IN] Algorithm type as defined by HW_CHECKSUM_ALGORITHM 00883 * @param vpAlgInfo [IN] Optional pointer to a HW_CUSTOMCRC16INFO or 00884 * HW_CUSTOMCRC32INFO structuer for HWCSA_CUSTOM_CRC16 00885 * and HWCSA_CUSTOM_CRC32 algorithms. If NULL, Hex 00886 * Workshop will use the user defaults. Must be NULL 00887 * for other algorithms. 00888 * @param qwOffset [IN] Starting offset location 00889 * @param qwLength [IN] Length (in bytes) to checksum, starting from qwOffset 00890 * @param vpResults [OUT] Buffer to place results 00891 * @param nResults [IN] Size of results buffer 00892 * 00893 * @see HW_CHECKSUM_ALGORITHM, hwChecksumLength 00894 * @see HW_CUSTOMCRC16INFO, HW_CUSTOMCRC32INFO 00895 * 00896 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00897 * codes 00898 */ 00899 HWAPI HWAPI_RESULT hwChecksumDocument(HWDOCUMENT hDocument, 00900 HW_CHECKSUM_ALGORITHM algorithm, 00901 const void* vpAlgInfo, 00902 QWORD qwOffset, 00903 QWORD qwLength, 00904 void* vpResults, 00905 size_t nResults) ; 00906 00907 /** @brief Calculate a checksum for a buffer 00908 * @ingroup checksums 00909 * 00910 * @param hSession [IN] Hex Workshop Plug-in session handle 00911 * @param algorithm [IN] Algorithm type as defined by HW_CHECKSUM_ALGORITHM 00912 * @param vpAlgInfo [IN] Optional pointer to a HW_CUSTOMCRC16INFO or 00913 * HW_CUSTOMCRC32INFO structuer for HWCSA_CUSTOM_CRC16 00914 * and HWCSA_CUSTOM_CRC32 algorithms. If NULL, Hex 00915 * Workshop will use the user defaults. Must be NULL 00916 * for other algorithms. 00917 * @param vBuffer [IN] Buffer to calculate checksum on 00918 * @param nBuffer [IN] Size of buffer to calculate checksum on 00919 * @param vpResults [OUT] Buffer to place results 00920 * @param nResults [IN] Size of results buffer 00921 * 00922 * @see HW_CHECKSUM_ALGORITHM, hwChecksumLength 00923 * @see HW_CUSTOMCRC16INFO, HW_CUSTOMCRC32INFO 00924 * 00925 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00926 * codes 00927 */ 00928 HWAPI HWAPI_RESULT hwChecksumBuffer(HWSESSION hSession, 00929 HW_CHECKSUM_ALGORITHM algorithm, 00930 const void* vpAlgInfo, 00931 const void* vBuffer, 00932 QWORD nBuffer, 00933 void* vpResults, 00934 size_t nResults) ; 00935 /** 00936 * @brief Get the editor caret position 00937 * @ingroup editor 00938 * 00939 * @param hDocument [IN] Hex Workshop document handle 00940 * @param pqwOffset [OUT] Offset address of the editing cursor 00941 * 00942 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00943 * codes 00944 */ 00945 HWAPI HWAPI_RESULT hwGetCaretPosition(HWDOCUMENT hDocument, 00946 QWORD* pqwOffset) ; 00947 00948 /** 00949 * @brief Set the editor caret position 00950 * @ingroup editor 00951 * 00952 * @note Selection is cleared on caret position change 00953 * 00954 * @param hDocument [IN] Hex Workshop document handle 00955 * @param qwOffset [IN] Offset address to place editing cursor 00956 * 00957 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00958 * codes 00959 */ 00960 HWAPI HWAPI_RESULT hwSetCaretPosition(HWDOCUMENT hDocument, 00961 QWORD qwOffset) ; 00962 00963 /** 00964 * @brief Get selection length of the hex editor window 00965 * @ingroup editor 00966 * 00967 * The selection starts at the curret caret position 00968 * @see hwGetCaretPosition to receive the caret position 00969 * 00970 * @param hDocument [IN] Hex Workshop document handle 00971 * @param pqwLength [OUT] Length of selection in bytes 00972 * 00973 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00974 * codes 00975 */ 00976 HWAPI HWAPI_RESULT hwGetSelection(HWDOCUMENT hDocument, 00977 QWORD* pqwLength) ; 00978 00979 /** 00980 * @brief Select data within the hex editor window 00981 * @ingroup editor 00982 * 00983 * The selection starts at the curret caret position 00984 * @see hwSetCaretPosition to adjust the starting offset 00985 * 00986 * @param hDocument [IN] Hex Workshop document handle 00987 * @param qwLength [IN] Length of selection in bytes 00988 * 00989 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 00990 * codes 00991 */ 00992 HWAPI HWAPI_RESULT hwSetSelection(HWDOCUMENT hDocument, 00993 QWORD qwLength) ; 00994 00995 00996 /** 00997 * @brief Get the window handle of the Hex Workshop frame window 00998 * @ingroup editor 00999 * 01000 * @param hSession [IN] Hex Workshop Plug-in session handle 01001 * 01002 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 01003 * codes 01004 */ 01005 HWAPI HWND hwGetWindowHandle(HWSESSION hSession) ; 01006 01007 01008 /** 01009 * @brief Log level definitions 01010 * @ingroup logging 01011 * 01012 * Log Levels definitions used by hwOutputLog. 01013 * 01014 * @see hwOutputLog 01015 */ 01016 typedef enum 01017 { 01018 HWLOG_DEBUG = 0, /**< Debug Log Level; only useful to plug-in author */ 01019 HWLOG_INFO = 1, /**< Info Log Level; information useful but not critical for end users */ 01020 HWLOG_WARN = 2, /**< Warning Log Level; warning for end user */ 01021 HWLOG_ERR = 3, /**< Error Log Level; An error condition has occurred */ 01022 } HWAPI_LOG_LEVEL ; 01023 01024 01025 /** 01026 * @brief Adds a log message to the Hex Workshop Output Window 01027 * @ingroup logging 01028 * 01029 * @param hSession [IN] Hex Workshop Plug-in session handle 01030 * @param level [IN] Log Level as defined by HWAPI_LOG_LEVEL 01031 * @param message [IN] Output text (CrLf not required) 01032 * 01033 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 01034 * codes 01035 */ 01036 HWAPI HWAPI_RESULT hwOutputLog(HWSESSION hSession, 01037 HWAPI_LOG_LEVEL level, 01038 LPCTSTR message, 01039 ...) ; 01040 01041 /** 01042 * @brief Updates the progress indicator in the Plug-in execute status dialog. 01043 * @ingroup editor 01044 * 01045 * The plug-in may call this API to update the status of the plug-in 01046 * execution. HWAPI_RESULT_USER_ABORT is returned if the user has cancelled 01047 * the operations. 01048 * 01049 * @note Call hwUpdateProgess(hSession, -1, NULL) to query for user cancel 01050 * status without updating the progress indicator. 01051 * 01052 * @param hSession [IN] Hex Workshop Plug-in session handle 01053 * @param percentComplete [IN] Percent complete (from 0 to 100) 01054 * @param status [IN] Short string to be placed in status dialog 01055 * 01056 * @return HWAPI_RESULT_SUCCESS on success, otherwise see hwapierr.h for error 01057 * codes 01058 */ 01059 HWAPI HWAPI_RESULT hwUpdateProgress(HWSESSION hSession, 01060 int percentComplete, 01061 LPCTSTR status) ; 01062 01063 /** @brief The plug-in requires an active file to operate 01064 * @ingroup entrypoints 01065 * 01066 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01067 * is only enabled when file is opened and active within the editor. 01068 * 01069 * @see HWPLUGIN_RequestCapabilities 01070 */ 01071 #define HWPLUGIN_CAP_FILE_REQUIRE 0x00000000 01072 01073 /** @brief The plug-in can operate with or without an active file 01074 * @ingroup entrypoints 01075 * 01076 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01077 * is always enabled. 01078 * 01079 * @see HWPLUGIN_RequestCapabilities 01080 */ 01081 #define HWPLUGIN_CAP_FILE_OPTIONAL 0x00000001 01082 01083 /** @brief The plug-in operates without an active file 01084 * @ingroup entrypoints 01085 * 01086 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01087 * is disabled if a file is opened and active within the editor. 01088 * 01089 * @see HWPLUGIN_RequestCapabilities 01090 */ 01091 #define HWPLUGIN_CAP_FILE_DISALLOW 0x00000002 01092 01093 /** @brief The plug-in should be automatically executed based on file extension 01094 * @ingroup entrypoints 01095 * 01096 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01097 * Hex Workshop calls the HWPLUGIN_RequestFileAutoexecExtensions entrypoint and 01098 * will automatically run the plug-in when a file with that extension is 01099 * opened. 01100 * 01101 * @see HWPLUGIN_RequestCapabilities 01102 * @see HWPLUGIN_RequestFileAutoexecExtensions 01103 */ 01104 #define HWPLUGIN_CAP_FILE_AUTOEXEC 0x00000008 01105 01106 /** @brief The plug-in requires an active selection within the editor 01107 * @ingroup entrypoints 01108 * 01109 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01110 * Hex Workshop disables the plug-in unless data is selected within the 01111 * editor. 01112 * 01113 * @see HWPLUGIN_RequestCapabilities 01114 */ 01115 #define HWPLUGIN_CAP_SELECTION_REQUIRE 0x00000010 01116 01117 /** @brief The plug-in can operate with or without an active selection 01118 * @ingroup entrypoints 01119 * 01120 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01121 * is enabled regardless of editor selection state. 01122 * 01123 * @see HWPLUGIN_RequestCapabilities 01124 */ 01125 #define HWPLUGIN_CAP_SELECTION_OPTIONAL 0x00000000 01126 01127 /** @brief The plug-in cannot operate with an active selection 01128 * @ingroup entrypoints 01129 * 01130 * When specified as part of HWPLUGIN_RequestCapabilities, the plug-in command 01131 * is disabled if data is selected within the editor. 01132 * 01133 * @see HWPLUGIN_RequestCapabilities 01134 */ 01135 #define HWPLUGIN_CAP_SELECTION_DISALLOW 0x00000020 01136 01137 /** @brief The plug-in does not support cancel 01138 * @ingroup entrypoints 01139 * 01140 * @note Plug-ins are assumed (and should) support cancel. hwUpdateProgress 01141 * should be used to update progress and determine if the user requested 01142 * a cancel. 01143 * 01144 * When specified as part of HWPLUGIN_RequestCapabilities, the cancel button is 01145 * disabled in the plug-in status dialog. 01146 * 01147 * @see HWPLUGIN_RequestCapabilities 01148 */ 01149 #define HWPLUGIN_CAP_NO_CANCEL 0x10000000 01150 01151 /** @name Required Entrypoints */ 01152 01153 01154 /** 01155 * @brief Called by Hex Workshop to identify a plug-in 01156 * @ingroup entrypoints 01157 * 01158 * Plug-in authors are required to implement the HWPLUGIN_Identify 01159 * entrypoint in their plug-in DLL and must return the plug-ins command(s) 01160 * as strings. The command strings are displayed under Hex Workshop's 01161 * Plug-ins menu and provided to the HWPLUGIN_RequestCapabilities and 01162 * HWPLUGIN_Execute entrypoints. 01163 * 01164 * Authors can define multiple plug-in commands or operations within a single 01165 * DLL. To specify multiple commands, delimit each command with a 01166 * semicolon(;). 01167 * 01168 * Authors may also include a backslash (\) to create a sub-menu item for 01169 * plug-ins within the Hex Workshop's plug-in menu. Only a single backslash 01170 * is supported. The full command name (including the slash) is used when 01171 * calling the other plug-in entrypoints. 01172 * 01173 * For example: 01174 * <pre> 01175 * HWAPIEP BOOL HWPLUGIN_Identify(LPTSTR lpstrPluginCommands, 01176 * size_t nMaxPluginCommand) ; 01177 * 01178 * _tcsncpy(lpstrPluginCommands, 01179 * _T("Plugin by Example, Inc."), 01180 * nMaxPluginCommand) ; 01181 * or 01182 * _tcsncpy(lpstrPluginCommands, 01183 * _T("Operation 1 by Example Inc.;Operation 2 by Example Inc.", 01184 * nMaxPluginCommand) ; 01185 * or 01186 * _tcsncpy(lpstrPluginCommands, 01187 * _T("Example Inc.\Operation 1;Example Inc.\Operation 2", 01188 * nMaxPluginCommand) ; 01189 * </pre> 01190 * 01191 * @note Each command string is limited to 127 characters and will be 01192 * truncated to 127 characters. 01193 * 01194 * @see HWPLUGIN_RequestCapabilities 01195 * @see HWPLUGIN_Execute 01196 * 01197 * @param lpstrPluginCommands [OUT] A buffer to place the plug-ins command 01198 * list. 01199 * @param nMaxPluginCommand [IN] The buffer length of lpstrPluginCommand in 01200 * TCHARs. Please use _tcsncpy as the buffer size may vary. 01201 * 01202 * @return TRUE on success or FALSE to disable the plugin 01203 */ 01204 HWAPIEP BOOL HWPLUGIN_Identify(LPTSTR lpstrPluginCommands, 01205 size_t nMaxPluginCommand) ; 01206 01207 01208 /** 01209 * @brief Called by Hex Workshop to determine capabilities for a plugin 01210 * @ingroup entrypoints 01211 * 01212 * Plug-in authors are required to implement the HWPLUGIN_RequestCapabilities 01213 * entrypoint in their plug-in DLL and must return one or more of the 01214 * HWPLUGIN_CAPABILITY_ flags. 01215 * 01216 * HWPLUGIN_RequestCapabilities is invoked for each of the command strings 01217 * specified by HWPLUGIN_Identify. 01218 * 01219 * The flags are used to determine when a Plug-in command should be enabled. 01220 * 01221 * For example: 01222 * <pre> 01223 * return HWPLUGIN_CAP_FILE_OPTIONAL | 01224 * HWPLUGIN_CAP_SELECTION_OPTIONAL ; 01225 * </pre> 01226 * 01227 * @param lpstrPluginCommand [IN] The command string provided by 01228 * HWPLUGIN_Identify 01229 * 01230 * @see HWPLUGIN_RequestCapabilities 01231 * @see HWPLUGIN_Execute 01232 * @see HWPLUGIN_RequestFileAutoexecExtensions 01233 * @see HWPLUGIN_CAP_FILE_REQUIRE 01234 * @see HWPLUGIN_CAP_FILE_OPTIONAL 01235 * @see HWPLUGIN_CAP_FILE_DISALLOW 01236 * @see HWPLUGIN_CAP_FILE_AUTOEXEC 01237 * @see HWPLUGIN_CAP_SELECTION_REQUIRE 01238 * @see HWPLUGIN_CAP_SELECTION_OPTIONAL 01239 * @see HWPLUGIN_CAP_SELECTION_DISALLOW 01240 * @see HWPLUGIN_CAP_NO_CANCEL 01241 * 01242 * @return One or more of the HWPLUGIN_CAP_ flags. 01243 */ 01244 HWAPIEP DWORD HWPLUGIN_RequestCapabilities(LPCTSTR lpstrPluginCommand) ; 01245 01246 /** 01247 * @brief Called by Hex Workshop to execute a plug-in command 01248 * @ingroup entrypoints 01249 * 01250 * @note The hDocument handle may be NULL if HWPLUGIN_CAPABILITY_NO_DOCUMENT 01251 * is specified by HWPLUGIN_RequestCapabilities 01252 * 01253 * @param lpstrPluginCommand [IN] The command string supplied as part of 01254 * HWPLUGIN_Identify 01255 * @param hSession [IN] Hex Workshop Plug-in session handle 01256 * @param hDocument [IN] Hex Workshop document handle 01257 * 01258 * @see HWPLUGIN_Identify 01259 * @see HWPLUGIN_RequestCapabilities 01260 * @see HWPLUGIN_RequestFileAutoexecExtensions 01261 * 01262 * @return TRUE if the operation was successful, otherwise false. 01263 */ 01264 HWAPIEP BOOL HWPLUGIN_Execute( LPCTSTR lpstrPluginCommand, 01265 HWSESSION hSession, 01266 HWDOCUMENT hDocument ) ; 01267 01268 /** @} */ 01269 /** @name Optional Entrypoints */ 01270 01271 /** 01272 * @brief Called by Hex Workshop to execute a plug-in command 01273 * @ingroup entrypoints 01274 * 01275 * Extensions must be delimited by a ; and are not case sensitive. Wildcards 01276 * are not supported. 01277 * 01278 * For example: 01279 * <pre> 01280 * HWAPIEP BOOL HWPLUGIN_RequestFileAutoexecExtensions(LPCTSTR lpstrPluginCommand, 01281 * LPTSTR lpstrExtensions, 01282 * size_t nExtensions) 01283 * { 01284 * _tcsncpy(lpstrExtensions, _T("mpeg;mpg;mp3"), nExtensions) ; 01285 * } 01286 * </pre> 01287 * 01288 * @note Only called if HWPLUGIN_CAP_FILE_AUTOEXEC is return by 01289 * HWPLUGIN_RequestCapabilities 01290 * 01291 * @param lpstrPluginCommand [IN] The command string supplied as part of 01292 * HWPLUGIN_Identify 01293 * @param lpstrExtensions [OUT] List of file extensions separated by ;s 01294 * @param nExtensions [OUT] Size of lpstrExtension buffer in TCHARs 01295 * 01296 * @see HWPLUGIN_Identify 01297 * @see HWPLUGIN_RequestCapabilities 01298 * @see HWPLUGIN_Execute 01299 * 01300 * @return TRUE if the operation was successful, otherwise false. 01301 */ 01302 HWAPIEP BOOL HWPLUGIN_RequestFileAutoexecExtensions(LPCTSTR lpstrPluginCommand, 01303 LPTSTR lpstrExtensions, 01304 size_t nExtensions) ; 01305 /** @} */ 01306 01307 #endif /* ] */