lkVCDimager is intened to be used by developpers.
All log-informations in the library, which normally would be directed to the console (like it is in the frontend(s)),
are send via Registred WindowsMessages to the calling application, which in this case must be a window.
Any parameter is transmitted using a struct.
The package comes in two files per release.
There is a binary-file, which contains :
And there is a sources-file, which contains a 'snapshot' of the sources at the time the release was published.
The sources also contains the static libraries of 'libxml2', which are linked in the project to get the target.
If you plan to rewrite the sources for your own project(s), be alerted that I've made slight changes in the libxml2,
see the header-files of libxml2 (which comes with the sources) to see which. If you don't care how libxml2 is used
(static or dynamic) then you'll better use one of these libraries. There is a library for the DEBUG- and one for the
RELEASE linkage.
Currently there is only 1 function that's been exported.
This function is called lkVCDxBuild.
Inside the library, lkVCDxBuild is declared as the following :
releases 1.0.7.10, 2.0.7.10 and 3.0.7.10 :
int lkVCDxBuild(HWND, LPCTSTR, lp_vcdxbuild_options);
release 4.0.7.10 and up :
int lkVCDxBuild(HWND, LPCTSTR, lp_vcdxbuild_options, BOOL* lpWantCancel=NULL);
In both cases, this function can be addressed via this typedef :
typedef int (lp_lkVCDxBuild)(HWND, LPCTSTR, lp_vcdxbuild_options);
or, if you want to use the 'lpWantCancel'-option (you need rel. 4.0.7.10 and up for that) :
typedef int (lp_lkVCDxBuild)(HWND, LPCTSTR, lp_vcdxbuild_options, LPBOOL);
lp_lkVCDxBuild is actually of type FARPROC, which is declared in MFC as
FAR* PASCAL.
When calling the function lkVCDxBuild, it would best to do so via a seperate worker-thread in the calling application.
While logging-information is send via windows-messages, using a seperate thread, the caller will have processing-time to process these messages,
otherwise the library 'freezes' as soon it sends a message to the caller..!
The function lkVCDxBuild returns a signed 32-bit integer, representing the 'errorlevel' which can have one of these values :
| -1 | : | wrong parameters were entered |
| 0 | : | successfull operation |
| 1 | : | an error occured in either the libvcd, vcdxml or libxml2 libraries |
| 2 | : | something wend wrong, resulting in memory leaks If this would occur, the library should be released from memory, in worst cases the system should be restarted -- sorry :-( Starting from rel. 4.0.7.10, this only would occur very rarely! |
lkVCDxBuild rel. <= 3.0.7.10 only took 3 parameters, in release >= 4.0.7.10 a 4th optional parameter is used.
| Parameter | Explanation | |
|---|---|---|
| HWND | : | the handle of the window that will process any messages the library will sent. If this handle is set to zero ('0'), lkVCDxBuild will retrieve a handle of the window which is currently active at the desktop via the WinAPI function HWND GetActiveWindow(); |
| LPCTSTR | : | a string of type const char* which tells the library from which message a unique ID should been retrieved.
The libray retrieves this ID via the WinAPI funtion UINT RegisterWindowMessage( LPCTSTR );. It's stronly recommended that you do the same with this message-string to retrieve an ID for your calling application. To let your window respond to this message, you must declare a message-function in the class-declaration using this syntax: LRESULT MsgFunc( WPARAM, LPARAM ); Then in the MessageMap you would enter a line like this : BEGIN_MESSAGE_MAP(<your_class>, <base_class>) ON_REGISTERED_MESSAGE( <registred msgID>, MsgFunc ) |
| lp_vcdxbuild_options | : | a ptr to a structure, defined in the file <vcd_exports.h>, of type vcdxbuild_options_t This structure contains the parameters, which lkVCDxBuild uses. One could compare these parameters as if they were entered at the commandline, like with the frontend of lkVCDxBuild. See the file vcd_exports.h for more information. |
| LPBOOL | : | this parameter is a ptr to BOOL, which is an unsigned 32-bit boolean. This parameter is only valid when library rel. >=4.0.7.10 is used. If you enter a non-NULL value, this value must remain valid until lkVCDxBuild has finished processing. Using this parameter, it would be possible to cancel lkVCDxBuild during long operations, like while scanning the MPeG-files and/or writing the final image-file. If used, this value should be initialized by the caller to FALSE (=0). lkVCDxBuild tests this value during those long operations for the value TRUE (=1). As soon it's TRUE, lkVCDxBuild will act like if an error would have occured, so 'normal' termination of the function can be done (releasing all used memory and closing any open files). |