#ifndef _SWUPLIB_HEADER_ #define _SWUPLIB_HEADER_ /* Siemens AG Mobile Radio Terminals Munich, Germany COMPANY CONFIDENTIAL All Rights Reserved .AUTHOR J. Kuenstner, ICP CD MP RD M 57 .SHORT_DESCR Interface to the WSWUPLIB-DLL .SW_COMPONENT Interface .SW_TYPE OTHER_PROCESS .VERSION 1.32 .DATE 2004-09-08 .STATUS FIRST_VERSION .CHANGE_CONTROL Version | Date | Changed by | Reason for Change --------+----------+------------+----------------------- 0.1 |XX.03.2000| JKue | file created...... --------+----------+------------+----------------------- 0.2 |10.03.2000| JKue | Added this Header --------+----------+------------+----------------------- 0.3 |30.06.2000| JKue | New Functions for Version-Checks | | | and support for Synch-Station --------+----------+------------+----------------------- 0.4 |15.07.2000| JKue | New Functions for Comport-Checks and | | | AMOUNT_OF_SWUP_PORTS increased to 12 --------+----------+------------+----------------------- 0.5 |18.12.2000| JKue | New Call-Back-Functions for checking Mobile-Types and Dates --------+----------+------------+----------------------- 0.6 |08.02.2001| JKue | Doxygen-Comments --------+----------+------------+----------------------- 0.7 |05.05.2001| J.Garrido | Sw_info extended --------+----------+------------+----------------------- 0.8 |15.05.2001| J.Garrido | Sw_info extended removed due lib compatibility --------+----------+------------+----------------------- 0.9 |19.05.2001| JKue | unknown projects --------+----------+------------+----------------------- 1.0 |29.05.2001| JKue | Update-Concept for K45 --------+----------+------------+----------------------- 1.10 |09.06.2001| JKue | Init-function with Interface-Version-Check --------+----------+------------+----------------------- 1.20 |10.06.2001| JKue | Had to change interface of functions WSwup_SetUpdateConceptMode() and | | | WSwup_CheckUpdateVoltage() --------+----------+------------+----------------------- 1.20 |11.06.2001| JKue | still 1.20 : some mor comments on the new update-concept --------+----------+------------+----------------------- 1.21 |13.07.2001| JKue | File-Debugging-Functionality --------+----------+------------+----------------------- 1.22 |17.07.2001| W. Hettich | new interface for heap method reading xbi data --------+----------+------------+------------------------------------------------- 1.23 |07.08.2001| W. Hettich | close up function for heap lib added --------+----------+------------+----------------------- 1.24 |2001-08-08| Schmittu/ | New Error-Functionality JKue | --------+----------+------------+----------------------- 1.25 |2001-08-29| Schmittu | new prototypes : WSwup_SetErrorTextBehaviourToEnduser | | | MAX_ENTRIES -> 50 --------+----------+------------+----------------------- 1.25 |2001-09-06| JKue | still 1.25 , only a comment was changed due to | | | an html-error for the doxygen-documentation --------+----------+------------+----------------------- 1.26 |2001-10-22| JKue | new function : WSwup_InstallSoftwareInfoCallBackFunction() | | | and the corresponding new callback-funtion --------+----------+------------+----------------------- 1.26 |2001-11-23| JKue | still 1.26 : Added some comment on | | | WSwup_CheckUpdateSuccess() --------+----------+------------+----------------------- 1.27 |2002-02-25| JKue | Added additional parameter for WSwup_InstallSoftwareInfoCallBackFunction() | | | This parameter selects the callbacktime --------+----------+------------+----------------------- 1.28 |2002-04-30| LSillge | New Functionprototype set PIN for Update added --------+----------+------------+----------------------- 1.29 |2002-05-26| J.Garrido | Read new file format for signature protection --------+----------+------------+----------------------- 1.29 |2002-11-18| JKue | still 1.29 : change some wrong comments eg: | - param ulSpeed in WSwup_SetUpdateConceptMode never existed ... --------+----------+------------+----------------------- 1.30 |2004-01-30| J.Garrido | Add install bfc callback funtion.Maintain the old interface | | | for backwards compatibility. | | | Add new fields in sw information structure. | | | szInfoDatabaseName | | | szInfoBaselineVersion | | | szInfoBaselineRelease | | | szSwupDllName --------+----------+------------+----------------------- 1.31 |2004-08-09| J.Garrido | Add new interfaces functions: | .- WSwup_LookForMobile | .- WSwup_SearchAvaliableComPort | Allowing the use of not limited port numbers. | .- Modify interface for WSwup_GetLastError and | WSwup_GetLastErrorString --------+----------+------------+----------------------- 1.32 |2002-09-08| J.Garrido | Remove AMOUNT_OF_SWUP_PORTS, not used. --------+----------+------------+----------------------- .STILL_TODO */ /* INDENT: -nbr -nce -ei -ip -lp -pro -sc -c:33 -cci:3 -cd:33 -ci:3 -cli:3 -cp:0 -d:0 -di:0 -i:3 -l:78 -lc:78 -tabs:3 -tabu */ /** * \file wswuplib.h * \brief This is the Export-Header for the WSWUPLIB-Library * */ /* *** INCLUDES *** ***************************************************** */ /* *** DEFINES *** ****************************************************** */ /* These two defines must be given to the function WSwup_InitLibrary() * The library will the do an equal-check and fail if it is not the same version * This is to avoid interface-conflicts, when an old Executable is executed * together with a newer DLL with a different interface ! * So : programmer of the library be careful on interface-changes ( avoid them * as far as possible, and if really necessary, the you have to increase the * version-defines, which forces the user of the DLL to a new compile with the * new interface, because the runtime-check will fail ! * */ #define WSWUPLIB_INTERFACE_VERSION_MAJOR 1 /**< Interface-Version of the whole library ( this file ), must be increased on interface-changes \ingroup initfunction */ #define WSWUPLIB_INTERFACE_VERSION_MINOR 32 /**< Interface-Version of the whole library, minor-number \ingroup initfunction */ #define AMOUNT_OF_UPDATES 4 /**< amount of parallel updates through different comports */ #define START_COM_SEARCH 0 /** Reset the com port search process */ #define CONTINUE_COM_SEARCH !START_COM_SEARCH /** Continue with the com search process at the last point */ /** * \def __SWUPLIBDLL__ * \brief Set this define on compiling the DLL. * This is normally done in the IDE on compliling the DLL ! * */ #ifdef COMPLETE_SERVICE_SWUP #define SWUPLIBDLLEXIMPORT #else #ifdef __SWUPLIBDLL__ /* ( done in the project-settings ! ) */ #define SWUPLIBDLLEXIMPORT __declspec(dllexport) #else #define SWUPLIBDLLEXIMPORT __declspec(dllimport) #endif #endif /* *** TYPEDEFS *** ****************************************************** */ /** * An enumeration for all possible Comports, as the number of * ports is not limited, don't use it any more * */ typedef enum { SwupCom1 = 0, /**< Comport 1 */ SwupCom2 = 1, /**< Comport 2 */ SwupCom3 = 2, /**< Comport 3 */ SwupCom4 = 3, /**< Comport 4 */ SwupCom5 = 4, /**< Comport 5 */ SwupCom6 = 5, /**< Comport 6 */ SwupCom7 = 6, /**< Comport 7 */ SwupCom8 = 7, /**< Comport 8 */ SwupCom9 = 8, /**< Comport 9 */ SwupCom10 = 9, /**< Comport 10 */ SwupCom11 = 10, /**< Comport 11 */ SwupCom12 = 11 /**< Comport 12 */ }t_SwupCom_old; /** * For backwards compatibility, serial number to be used. */ typedef unsigned int t_SwupCom; /** * Different parts of the whole library, for which the user can request version-information. * Give one of this values to function WSwup_GiveVersionInformation() and it will return the information * about the requested part. * * \ingroup dllversion */ typedef enum { enSwupLibDll, /**< information about the whole wrapper */ enSwupSeriDll, /**< information about the serial DLL */ enBootStrapDll, /**< information about the BootStrapLoader-DLL itself */ enUpdateSW /**< information about the MobileSW-Part that is contained in the BSL-DLL */ } t_InfoSelector; /** * Version-Information for the different parts of the Library. * The library itself is split into different DLLs, some of them are * loaded on runtime. So the user can call the function WSwup_GiveVersionInformation * and will find the information about the different parts * in this returned structure. * * \ingroup dllversion */ typedef struct { int nStructSize; /**< must be loaded with sizeof( struct ) to avoid Consistency-errors */ char szDescription[100]; /**< Description, ex: "BSL-DLL for EGOLD+, Synchstation" */ char szDeveloper[10]; /**< the developer, ex: "kuenstnj" / "official" */ char szDateTime[18]; /**< Date and Time, ex: "30.06.00 20:15:17 " */ int nVersionMajor; /**< the Major-Version-Nr ex: 1 */ int nVersionMinor; /**< the Minor-Version-Nr ex: 25 */ } t_VersionInformation; /** * Structure with Information about the SW in the XBI-File or the Mobile itself. * This Information-Structure will be filled on call of function WSwup_ReadXbiFile and * pointers to two of this structs will be given on Consistence-Errors, when eg. the * SW already contained in the mobile is newer than the XBI-File that is going to be * updated ( see MobileSwUpdateConsistenceProblemCallBack() ). * * \ingroup filefun */ typedef struct { char szProductType[16]; /**< Official Name of the product , ex: S35 , C3I etc */ char szProjectName[16]; /**< Develop-Name of the product , ex: epp35a, epp35ci etc */ char szProductSVN[10]; /**< Official SVN-String, ex: "SVN 1" */ char szCompileDate[9]; /**< Date the SW was compiled, ex: "05.03.00" */ char szCompileTime[9]; /**< Time the SW was compiled, ex: "12:31:47" */ char szSwType [20]; /**< Type of the SW , ex: "MobSw" */ char szNewSplitIdentifier [16]; /**< Kind of Split, ex: "SplitOnly" */ char szCommentAboutSplitEntity [20]; /**< if exist then the header value , ex: "Tegig", if not ?? */ char szInfoDatabaseName[0x20];/**< CMT/Continuus Database Name (per default : "DB Name") */ char szInfoBaselineVersion[0x40];/**< CMT/Continuus Baseline Version (per default : "BL Version") */ char szInfoBaselineRelease[0x40];/**< CMT/Continuus Baseline Release (per default : "BL Release") */ char szSwupDllName[17]; /**< dll to use for the sw update */ } t_SwInformation; #define MAX_ENTRIES 50 /**< Amount of entries in the error-"stack" \ingroup errorfun */ #define NO_PARAM "" /**< an empty parameter-list \ingroup errorfun */ #define SIZE_OF_PINFO 10 /**< max amount of parameters for errors \ingroup errorfun */ #define SIZE_OF_PSTRING 2000 /**< maximum size of a error-string-parameter \ingroup errorfun */ /** * A structure to allow passing of parameters for error-messages from the Lib to the user of the Lib. * If you need internationalisation in your application, you have to deal with error-strings * yourself outside the library.
* To allow the library on errors to pass parameters to the user of the library this * structure was introduced.
* You will retrieve a pointer to this structure via call of WSwup_GiveLastError() . * The first element in the struct is the error-number itself. * The second element is a simplified format-string ( like in printf but without % ) that * tells the user of the library how many and in which order additional parameters * are stored in the third and fourth elements of the struct.
* There is only a distinction between strings and numerical integer values ( no floats ), * this means for example if the format-string contains something like "dsxs" ,that * the first and the third error-parameter ( d and x ) will be stored in * t_ErrorStruct.ulParamValue and the second and forth parameter containg two strings * are stored in t_ErrorStruct.ucParamString.
* If you need more information you should have a look at the also provided err_demo.c. * * \ingroup errorfun * */ typedef struct { DWORD dwErrorNumber; /**< the error-enum */ unsigned char ucParamInfo[SIZE_OF_PINFO +1]; /**< info about the validity of the following params + EOS */ LONG ulParamValue[5]; /**< variables that will be inserted in the indicated string at %d,%x,... */ unsigned char ucParamString[5][SIZE_OF_PSTRING]; /**< variables that will be inserted in the indicated string at %s */ } t_ErrorStruct; /* *** EXTERNALS *** **************************************************** */ /* *** CONSTANTS *** ***************************************************** */ /* *** VARIABLES *** **************************************************** */ /* *** PROTOTYPES *** *************************************************** */ /* *** MODUL COMMENTS *** *********************************************** */ /* *** FUNCTIONS *** **************************************************** */ /*************************************************************************************************************** * * * Init-Functions * * ***************************************************************************************************************/ /** * \defgroup initfunction Init-Function for the whole Library/DLL */ /* ------------------------------------------------------------------------ * WSwup_InitLibrary * ------------------------------------------------------------------------ */ /** * This function must be called by every user of the library once on starting. * This intention of this function is to make a interface-compatibility-check * at runtime, so every user of the library has to call this function once * before using the library.
* The user has to pass the two defines: * - WSWUPLIB_INTERFACE_VERSION_MAJOR * - WSWUPLIB_INTERFACE_VERSION_MINOR * * to the function. * If the given version is different from the one which the library expects, * ( the one it had on its own compile-time ) * the function will return FALSE and the library will not work. * This is to prevent library-users from unexpected runtime-errors in their executables * due to a new interface and new DLLs but an old Executable ! * * \param wMajorNumber : must be the given define WSWUPLIB_INTERFACE_VERSION_MAJOR * \param wMinorNumber : must be the given define WSWUPLIB_INTERFACE_VERSION_MINOR * * \retval TRUE -> Library is initialised, version-information is ok * \retval FALSE -> version-check failed, library does not work * * \ingroup initfunction * */ BOOL SWUPLIBDLLEXIMPORT WSwup_InitLibrary( WORD wMajorNumber, WORD wMinorNumber ); /*************************************************************************************************************** * * * Comport-Information-Functions * * ***************************************************************************************************************/ /** * \defgroup comportinfo Comport-Information-Functions */ /* ------------------------------------------------------------------------ * WSwup_LookForMobile * ------------------------------------------------------------------------ */ /** * This function look for a siemens telephone on the desired com port with de * desired baudrate. * There is no guaranty, that the update with this baudrate will work ! * \param ComPort Desired comport number to be tested ( starting at 0 for "COM1") * \param Baudrate Desired baudrate to be use in the test. * * \retval TRUE a telephone was found * \retval FALSE no compatible telephone found. * * \ingroup comportinfo * */ BOOL SWUPLIBDLLEXIMPORT WSwup_LookForMobile(t_SwupCom ComPort, DWORD Baudrate); /* ------------------------------------------------------------------------ * WSwup_SearchAvaliableComPort * ------------------------------------------------------------------------ */ /** * This function looks in the registry for avaliable com ports which supports rs232. * There is no guaranty, that the update with this baudrate will work ! * Use it with the Option START_COM_SEARCH for the first call to start up, next ports will be get * by using the option CONTINUE_COM_SEARCH. * * \param pszComName a string where to place the name of the port ( "COM1", "COM123" ) * \param pszComDesc a string where to place the desription of the port. Usually in the form * "device/serial0" * \param Option a integer meaning the start up or the continue of the search. * * \retval TRUE everithing worked properly * \retval FALSE End of search, no more ports avaliable. Or an error is ocurred. * * \ingroup comportinfo * */ BOOL SWUPLIBDLLEXIMPORT WSwup_SearchAvaliableComPort ( char * pszComName, char * pszComDesc ,unsigned int Option ); /* ------------------------------------------------------------------------ * WSwup_CheckComPortAndSpeed * ------------------------------------------------------------------------ */ /** * This function only tries to open the selected comport with the given baudrate. * In all cases ( besides comport already open ) the comport will be closed after this try. * It returns the result from opening the comport, so its possible to determine * if the win-system allows this baudrate on this comport. * There is no guaranty, that the update with this baudrate will work ! * * * \param WhichCom a t_SwupCom-enum, which comport should be tried * \param dwBaudrate a dword meaning the Baudrate at which the comport should be tried * * * * \retval TRUE It is possible ( from WIN-System-side ) to open the Comport at this baudrate * \retval FALSE Either Comport not available or this baudrate not possible * * \ingroup comportinfo * */ BOOL SWUPLIBDLLEXIMPORT WSwup_CheckComPortAndSpeed( t_SwupCom WhichCom , DWORD dwBaudrate ); /*************************************************************************************************************** * * * DLL-Version-Information-Functions * * ***************************************************************************************************************/ /** * \defgroup dllversion DLL-Version-Information-Functions */ /* ------------------------------------------------------------------------ * WSwup_GiveVersionInformation * ------------------------------------------------------------------------ */ /** * Returns Version Information about the different Parts of WSWUPLIB. * Since the SWUPLIB-functionality is contained in 3 different DLLs, * and one of them is dynamically loaded for different processor-types, * it is possible to retrieve some information about the DLLs. * * * \param WhichInfo a t_InfoSelector , about which part the information is to be retrieved * * \param pInformation a ptr to a t_VersionInformation , that will be filled with * the requested information. * Attention: pInformation->nStructSize must be filled from the caller with * sizeof( t_VersionInformation ) to avoid conflicts on future enhancements * * \retval TRUE Information-struct is filled with info * \retval FALSE Information not available, ex. the DLL is not yet loaded * * \ingroup dllversion */ BOOL SWUPLIBDLLEXIMPORT WSwup_GiveVersionInformation( t_VersionInformation * pInformation, t_InfoSelector WhichInfo ); /*************************************************************************************************************** * * * Synch-Station specific Functions * * ***************************************************************************************************************/ /** * \defgroup synchstation Synch-Station specific Functions */ /* ------------------------------------------------------------------------ * WSwup_PrepareForUpdateWithSynchStation * ------------------------------------------------------------------------ */ /** * * Prepares for performing the update via Synch-Station. * The Bootstrap-Loader for a Synch-Station is different to a normal BSL. * Since the Bootstraploader-DLL is dynamically loaded on File-Reading, * this function must be called in advance, to force loading a different, * synch-station-specific DLL on FileReading * * \param fSynchStationPresent Boolean Flag for presence/absence of Synch-Station * * * \return void * * \ingroup synchstation */ void SWUPLIBDLLEXIMPORT WSwup_PrepareForUpdateWithSynchStation( BOOL fSynchStationPresent ); /* ------------------------------------------------------------------------ * WSwup_ReloadUpdateDll * ------------------------------------------------------------------------ */ /** * * Reloads the DLL that is responsible for performing the Update. * If - after reading the file - the decision is made, that this update * is via a synch-station, the DLL must be relodaded, in order to get * the correct Bootstraploader. * => * - call WSwup_PrepareForUpdateWithSynchStation( TRUE ) * - call this function * * * \retval TRUE Everything is okay * \retval FALSE something went wrong * * \ingroup synchstation */ BOOL SWUPLIBDLLEXIMPORT WSwup_ReloadUpdateDll( void ); /*************************************************************************************************************** * * * ERROR-Functions, to get information about the last ERROR * * ***************************************************************************************************************/ /** * \defgroup errorfun ERROR-Functions, to get information about the last ERROR */ /* ------------------------------------------------------------------------ * WSwup_GetLastError * ------------------------------------------------------------------------ */ /** * Returns an specific Error-Code about last Error on this comport. * Retrieves the last occured Error for the specified COM-Port * ( almost useless, normally use WSwup_GetLastErrorString ) * Dont use this function any longer its obsolete and will * be killed in one of the next releases !
* Either use function WSwup_GetLastErrorString() to get an * english string or use function WSwup_GiveLastError() and deal * with it's information outside the library. * * \param ComPort ComPort on which the Error cccured * * \return The Error-Code * * \ingroup errorfun */ DWORD SWUPLIBDLLEXIMPORT WSwup_GetLastError( WORD wUpdateNr ); /* ------------------------------------------------------------------------ * WSwup_SetErrorTextBehaviourToEnduser * ------------------------------------------------------------------------ */ /** * Switches the behaviour of function WSwup_GetLastErrorString() to a less informative behaviour. * Has to be called in an enduser-update when not dealing yourself with error-strings, this means * when you are hapyy with english text. Normally on an enduser-update you should deal with different * languages and interpret the errors outside the library by yourself using function : * WSwup_GiveLastError( ) and implement something equal to the swupdemo-error-handling. * * \param fEndUser TRUE means enduser * FALSE means developper * * \retval none * * \ingroup errorfun * */ void SWUPLIBDLLEXIMPORT WSwup_SetErrorTextBehaviourToEnduser( BOOL fEndUser); /* ------------------------------------------------------------------------ * WSwup_GetErrorString * ------------------------------------------------------------------------ */ /** * Retrieves the Error-String of the last Error for the given ComPort. * * \param ComPort ComPort on which the Error cccured * * \return The Error-Code-String * * \ingroup errorfun */ char SWUPLIBDLLEXIMPORT * WSwup_GetLastErrorString( WORD wUpdateNr ); /* ------------------------------------------------------------------------ * WSwup_GiveLastError * ------------------------------------------------------------------------ */ /** * Returns the last Error for the indicated updatenumber with its specific parameters. * For a more detailled explanation see a the declaration of \ref t_ErrorStruct or * have a look at the also provided err_demo.c
* * * * \param wUpdateNr : the update-Nr for which you want to retrieve the error-information. * * \return t_ErrorStruct -> a pointer to a \ref t_ErrorStruct - structure * * \ingroup errorfun * * * */ SWUPLIBDLLEXIMPORT t_ErrorStruct * WSwup_GiveLastError ( WORD wUpdateNr ); /*************************************************************************************************************** * * * BFC-Lib-Functions, used before and after SOFTWARE-Update to check if a * Software-Update is possible and if it was successfull ! * * ***************************************************************************************************************/ /** * \defgroup bfcfun BFC-Lib-Functions, used before and after SOFTWARE-Update */ /** * Callbackfunction for VoltageCheck that is performed. * On call of function WSwup_CheckUpdateVoltage this callback-function is called several times * to allow the user of the library to show the progress. * \param wUpdateNr This parameter is the Update-Nr * \param unMaxCalls This second Parameter is the Max-Amount of Calls of this CallbackFunction * \param unCurrCall this parameter is the current Call-Number. It can happen that not all Callbacks * are done ! * \return void * \ingroup bfcfun */ typedef void ( * VoltageCheckCallBack ) ( WORD wUpdateNr, unsigned int unMaxCalls, unsigned int unCurrCall ); /** * Callbackfunction for UpdateSuccess that is performed after swup. * On call of function WSwup_CheckUpdateSuccess this callback-function is called several * times to allow the user of the library to show the progress. * \param wUpdateNr First Parameter is the Update-Nr * \param unMaxCalls Second Parameter is the Max-Amount of Calls of this CallbackFunction * \param unCurrCall Third parameter is the current Call-Number. It can happen that not all Callbacks * are done ! * \return void * \ingroup bfcfun */ typedef void ( * UpdateSuccessCallBack) ( WORD wUpdateNr, unsigned int unMaxCalls, unsigned int unCurrCall ); /* ------------------------------------------------------------------------ * WSwup_InstallBfbCallBackFunctions * ------------------------------------------------------------------------ */ /** * Call WSwup_InstallBfcCallBackFunctions. Only for back-compatibility. * \param pfnVoltageCheck Pointer to a CallbackRoutine that is called on Voltage-Check * \param pfnSuccessCheck Pointer to a CallbackRoutine that is called on Update-Success * * \return void * * \ingroup bfcfun */ void SWUPLIBDLLEXIMPORT WSwup_InstallBfbCallBackFunctions( VoltageCheckCallBack pfnVoltageCheck, UpdateSuccessCallBack pfnSuccessCheck ); /* ------------------------------------------------------------------------ * WSwup_InstallBfcCallBackFunctions * ------------------------------------------------------------------------ */ /** * Installs the needed callbackfunctions for Pre and Post-Checks via BFC-Library. * If the user of the library wants to perform voltagecheck before the software-update * itself and wants to perform the updatesuccess-check after the software-update with * the functions WSwup_CheckUpdateVoltage and WSwup_CheckUpdateSuccess he first must * install the callbackfunctions that will be called from inside the library to * show the progress in the different functionalities. * * \param pfnVoltageCheck Pointer to a CallbackRoutine that is called on Voltage-Check * \param pfnSuccessCheck Pointer to a CallbackRoutine that is called on Update-Success * * \return void * * \ingroup bfcfun */ void SWUPLIBDLLEXIMPORT WSwup_InstallBfcCallBackFunctions( VoltageCheckCallBack pfnVoltageCheck, UpdateSuccessCallBack pfnSuccessCheck ); /* ------------------------------------------------------------------------ * WSwup_CheckUpdateVoltage * ------------------------------------------------------------------------ */ /** * Tries to communicate to a "living" mobile to determine if the voltage is ok. * Switches the Mobile on, if necessary and afterwards switches it off, so * that afterwards the softwareupdate itself can be performed. * Calls several times the pfnVoltageCheck CallbackFunction.
* In case this update is an update with the new behaviour ( introduced for * the K45-family ) set via WSwup_SetUpdateConceptMode() this function * has a slightly different behaviour: * - this routine MUST be called, because it initiates the update ! * - ( with BootStrapMode this routine is an option ) * - it does not try to switch on the mobile, endusers dont have an ignition line. * - due to this : if connection via ping is not possible, this routine fails. * - the filetype is checked, only a complete Mobile-SW can be updated with this new mode * - partitial SW ( Diff/Tegic/Language/... ) will be refused. * - after having pinged and checked the voltage, this routine forces the mobile into * the new update-mode, without really switching off. * - due to this it's necessary to pass the new baudrate-parameter, which will be used for the following * update-procedure itself * - after sucessfully returning from this function, the WSwup_PerformSoftwareUpdate() function must * be called, because the mobile is already in update-mode ! * * * \param wUpdateNumber Number of the current Update * \param WhichCom ComPort of this Update * * \param punVoltage Pointer to the Voltage in Millivolt * \param ulSpeed the max speed that can be driven on this PC , ( use ADDIDATA-Baudrates even if * you have a fastboot-card installed ) * * \retval TRUE everything is fine * \retval FALSE Some Error occurred, call WSwup_GetLastError() or WSwup_GetLastErrorString() * * \ingroup bfcfun */ BOOL SWUPLIBDLLEXIMPORT WSwup_CheckUpdateVoltage( WORD wUpdateNumber , t_SwupCom WhichCom , unsigned short * punVoltage, unsigned long ulSpeed ); /* ------------------------------------------------------------------------ * WSwup_CheckUpdateSuccess * ------------------------------------------------------------------------ */ /** * Checks if Mobile-SW-Update was successfull. * Tries to switch on the Mobile and to ping it, to check if the Mobile-SW is okay.
* NEWAfterwards the mobile is being switched OFF, to avoid errors * with different behaviour between switching on via tool and via key-press.
* Problems are: AT-C doesnt work correctly, Carkit doesnt work correctly. * * \param wUpdateNumber Number of the current Update * \param WhichCom ComPort of this Update * * * \retval TRUE everything is fine * \retval FALSE Some Error occurred, call WSwup_GetLastError() or WSwup_GetLastErrorString() * * \ingroup bfcfun */ BOOL SWUPLIBDLLEXIMPORT WSwup_CheckUpdateSuccess( WORD wUpdateNumber , t_SwupCom WhichCom ); /*************************************************************************************************************** * * * FILE-Functions, read XBI-File , release XBI-File, get Information about XBI-File * * ***************************************************************************************************************/ /** * \defgroup filefun FILE-Functions */ /** * Callbackfunction for FileReading. * This function is called several times from inside the library during reading of the * XBI-File to give the user of the library the possibility to show the read-progress to the * enduser. * \param ulAmountOfBytesToRead First Parameter the is the Amount of Bytes that are to be read * \param ulCurrentRead Second Parameter is the current amount of bytes Read * \return void * * \ingroup filefun * */ typedef void ( * FileReadProgressCallBack ) ( unsigned long ulAmountOfBytesToRead, unsigned long ulCurrentRead ); /** * Prepares the WSWUP-Library for updating an "unknown" project. * This function must be called before calling of WSwup_ReadXbiFile() in case the * development-project is not known to the library. This only happens during development-phase * on introduction of new projects. Normally the Library must know all projects to load the right * Update-DLL depending on the read in XBI-File. So if a new project is derived from an already known * project, this function can be called to tell the library which update-dll shall be loaded, if an * specific unknown project happens to be in the XBI-File. * * \param pszUnknownProjectName Name of the project that is unknown to library up to now. * \param pszDerivedFromKnownProjectName Name of the project that is known to library and who's update-DLL should be used. * \return void * * \ingroup filefun * */ void SWUPLIBDLLEXIMPORT WSwup_PrepareForUpdateWithUnknownProject( char * pszUnknownProjectName, char * pszDerivedFromKnownProjectName ); /* ------------------------------------------------------------------------ * WSwup_ReadXbiFile * ------------------------------------------------------------------------ */ /** * Reads the XBI-File with the given name into memory, so a swup can be performed. * Is NOT done in a THREAD, so if the function returns the data is read. * Several times during the read-prcess the via function-ptr given callbackfunction * is called so that you can show the readprogress to the enduser. * * \param pszXbiName Name of the XBI-File to be read with complete path and extension * \param pfnReadProgress Pointer to a callbackfunction to show read progress * * \param pSwInformation Pointer to a t_SwInformation Struct where the Information about the * SW will be stored by this function * * \retval TRUE -> everything is fine * \retval FALSE -> Some Error occurred, call WSwup_GetLastFileError() * * \ingroup filefun */ BOOL SWUPLIBDLLEXIMPORT WSwup_ReadXbiFile( t_SwInformation * pSwInformation, FileReadProgressCallBack pfnReadProgress, char * pszXbiName ); /* ------------------------------------------------------------------------ * WSwup_ReadXbiFileFromHeap * ------------------------------------------------------------------------ */ /** * Checks an XBI-File in heap so a swup can be performed. * This is to provide a similiar functionality like function * WSwup_ReadXbiFile() . * The difference is, that the user of the library has to allocate the * needed memory by himself. * He also has to read in the input-file as a binary file to the allocated heap. * Before end of the program this memory must be freed by the user of the library. * Attention: The library uses this heap, so you are * not allowed to free this memory before the end of your program. * * * \param pSwInformation Pointer to a t_SwInformation Struct where the Information about the * SW will be stored by this function * \param pucMem Pointer to start of heap with file, read-only access from inside library * \param ulBytesInHeap bytes in heap * * \retval TRUE -> everything is fine * \retval FALSE -> Some Error occurred, call WSwup_GetLastFileError() * * \ingroup filefun */ BOOL SWUPLIBDLLEXIMPORT WSwup_ReadXbiFileFromHeap( t_SwInformation * pSwInformation, unsigned char * pucMem, unsigned long ulBytesInHeap ); /* ------------------------------------------------------------------------ * WSwup_GivePtrToBinData * ------------------------------------------------------------------------ */ /** * once WSwup_ReadXbiFileFromHeap() is successfully called, this function * delivers a ptr to start of bin data in heap. * * Usually there is no need to call this function, the heap ptr * is used in right manner internally, but maybe there is some interest... * * \retval NULL -> WSwup_ReadXbiFileFromHeap() successfully called ? * \retval ptr to bin data in heap * * \ingroup filefun */ unsigned char SWUPLIBDLLEXIMPORT * WSwup_GivePtrToBinData( void ); /* ------------------------------------------------------------------------ * WSwup_GetLastFileError * ------------------------------------------------------------------------ */ /** * Returns a pointer to a string describing the last error occured on FileReading. * Currently the error-strings are hardcoded in english language in the library. * * * \return pointer to a descriptive string about an FileReadError * * \ingroup errorfun * */ char SWUPLIBDLLEXIMPORT * WSwup_GetLastFileError( void ); /* ------------------------------------------------------------------------ * WSwup_CloseXbiFile * ------------------------------------------------------------------------ */ /** * Releases all memory allocated on WSwup_ReadXbiFile . * Must be called before reading another file, before closing * the program or if an Error occured on WSwup_ReadXbiFile() ! * * * \return void * * \ingroup filefun */ void SWUPLIBDLLEXIMPORT WSwup_CloseXbiFile( void ); /* ------------------------------------------------------------------------ * WSwup_CloseXbiFile * ------------------------------------------------------------------------ */ /** * Releases all memory allocated inside of WSwup_ReadXbiFileFromHeap . * Must be called before: * - closing the program * - before reading another file into your heap * - or if an error occured on WSwup_ReadXbiFileFromHeap() ! * * * \return void * * \ingroup filefun */ void SWUPLIBDLLEXIMPORT WSwup_CloseXbiFileHeap( void ); /*************************************************************************************************************** * * * DEBUG-Functions for enabling and disabling OnLine-Debug * I recommend DEBUGVIEW from www.sysinternals.com as viewer * Currently only works in the debug-versions of the DLLs ! * ***************************************************************************************************************/ /** * \defgroup debugfun DEBUG-Functions for en/disabling OnLine-Debug */ /** * Enable one or more of the follwing defines ( combined via | ) to enable debugging for the differnt parts. */ #define MAIN_DEBUG_GROUP 0x01 /**< Enable Main-Functionality Debugging \ingroup debugfun */ #define FILE_DEBUG_GROUP 0x02 /**< Enable File-Function Debugging \ingroup debugfun*/ #define COMM_DEBUG_GROUP 0x04 /**< Enable Debugging on Communciation-Functions \ingroup debugfun */ #define BFC_DEBUG_GROUP 0x08 /**< Enable Debugging on BFC-Communciation-Functions \ingroup debugfun */ /** * Debugging-Level * \ingroup debugfun */ typedef enum { enNoDebug = 0, /**< No debugging */ enLowDebug = 1, /**< Low debugging */ enMidDebug = 2, /**< Mid-Range debugging */ enHighDebug = 3 /**< Debug everything */ } t_DebugLevel; /* ------------------------------------------------------------------------ * WSwup_EnableOnlineDebugging * ------------------------------------------------------------------------ */ /** * Enables Online Debugging on the requested DebugLevel for the requested Groups * * \param RequestedDebugLevel The DebugLevel ( a t_DebugLevel enum ) * \param wRequestedDebugGroups a combination of the above Debug-Groups * * \return void * * \ingroup debugfun */ void SWUPLIBDLLEXIMPORT WSwup_EnableOnlineDebugging( t_DebugLevel RequestedDebugLevel, WORD wRequestedDebugGroups ); /* ------------------------------------------------------------------------ * WSwup_DisableOnlineDebugging * ------------------------------------------------------------------------ */ /** * Disables Online Debugging * * \return void * * \ingroup debugfun */ void SWUPLIBDLLEXIMPORT WSwup_DisableOnlineDebugging( void ); /* ------------------------------------------------------------------------ * WSwup_EnableFileDebugging * ------------------------------------------------------------------------ */ /** * Enables File Debugging on the requested DebugLevel for the requested Groups * * \param RequestedDebugLevel The DebugLevel ( a t_DebugLevel enum ) * \param wRequestedDebugGroups a combination of the above Debug-Groups * \param szFilePrefix Name of the files to debug into, without extension ! * * \return void * * \ingroup debugfun */ void SWUPLIBDLLEXIMPORT WSwup_EnableFileDebugging( t_DebugLevel RequestedDebugLevel, WORD wRequestedDebugGroups, char *szFilePrefix ); /* ------------------------------------------------------------------------ * WSwup_DisableFileDebugging * ------------------------------------------------------------------------ */ /** * Disables File Debugging * * \return void * * \ingroup debugfun */ void SWUPLIBDLLEXIMPORT WSwup_DisableFileDebugging( void ); /*************************************************************************************************************** * * * SOFTWARE-Update-Functions * * ***************************************************************************************************************/ /** * \defgroup swupfun SOFTWARE-Update-Functions * The whole softwareupdate is performed with one functioncall : WSwup_PerformSoftwareUpdate() * The function itself terminates directly, it will generate a thread. * So it is possible to call the function several times to perform software-updates * in parallel on different comports. * In the generated thread the following steps are performed: * - connection to a switched off mobile with the bootstraploader * - transmission of the update-sw * - erasure of the flash * - transmission of the new mobile-software * * To allow communication between the library and the mainprogram, the user * has to install several callbackfunctions which will be called from inside the * library. The callbackfunctions are called in this order : * - BootstrapProgressCallBack() * - UpdateSwTransmissionStartCallBack() * - UpdateSwTransmissionProgressCallBack() * - FlashTypeCallBack() * - EraseProgressCallBack() * - MobileSwTransmissionStartCallBack() * - MobileSwTransmissionProgressCallBack() * - MobileSwUpdateSuccessCallBack() * * In case this is an update following the new concept ( introduced for the K45-family ) * set via WSwup_SetUpdateConceptMode() the following call-back-functions will * NOT be called, because these steps are not done from inside the library, * the mobile will perform this steps by itself automatically: * - BootstrapProgressCallBack() * - UpdateSwTransmissionStartCallBack() * - UpdateSwTransmissionProgressCallBack() * * If an error occurs during the update-process the following callbackfunction will * be called from inside the library: * - MobileSwUpdateErrorCallBack() * * Before erasure of the flash a consistence-check between the new software and the * mobile already in the mobile will be performed. * If a consistence-error is detected, the following function will be called: * - MobileSwUpdateConsistenceProblemCallBack() */ /** * Callbackfunction for Bootstraploader * * \param wUpdateNr, First Parameter is the Update-Nr * \param unMaxCalls Second Parameter is the Max-Amount of Calls of this CallbackFunction * \param unCurrCall Third parameter is the current Call-Number. It can happen that not all Callbacks * are done ! * \return void * * \ingroup swupfun * */ typedef void ( * BootstrapProgressCallBack ) ( WORD wUpdateNr, WORD unMaxCalls, WORD unCurrCall ); /** * Callbackfunction for UpdateSwTransmissionStart. * This callbackfunction will be called once before the update-sw is * beeing transmitted to mobile. If you want to show the percentage * of update-sw beeing transmitted, you have to store the parameter * ulBytesToTransfer and compare it against the values given by the * calls of the callbackfunction UpdateSwTransmissionProgressCallBack() * * \param wUpdateNr First Parameter is the Update-Nr * \param ulBytesToTransfer Second Parameter is the amount of data to be sent * \return void * * \ingroup swupfun * */ typedef void ( * UpdateSwTransmissionStartCallBack ) ( WORD wUpdateNr, unsigned long ulBytesToTransfer ); /** * Callbackfunction for UpdateSwTransmissionProgress. * This callbackfunction will be called several times during the transmission of the * update-sw. This software is executed in the ram of the mobile and is responsible * for the erasure of the flash and the reprogramming of the flash with the new mobile-sw. * * \param wUpdateNr First Parameter is the Update-Nr * \param ulBytesTransfered Second Parameter is the current amount of sent data * \return void * * \ingroup swupfun */ typedef void ( * UpdateSwTransmissionProgressCallBack ) ( WORD wUpdateNr, unsigned long ulBytesTransfered ); /** * Callbackfunction for FlashType. * This callbackfunction is called once before the flash is beeing * erased and it gives the actual flashcode as parameter. * * \param wUpdateNr First Parameter is the Update-Nr * \param wFlashId Second Parameter is the Flash-Code * \param pszFlashString Third Parameter is a string to an Description of the Flash * \return void * * \ingroup swupfun */ typedef void ( * FlashTypeCallBack ) ( WORD wUpdateNr, WORD wFlashId, char * pszFlashString ); /** * Callbackfunction for EraseProgress. * This callbackfunction is called several times during the flash-erase-process. * * \param wUpdateNr First Parameter is the Update-Nr * \param wAmountFlashBlocks Second Parameter is the number of flash-blocks to erase * \param wCurrentBlock Third Parameter is the current number of flashblock that is beeing erased * \return void * * \ingroup swupfun */ typedef void ( * EraseProgressCallBack ) ( WORD wUpdateNr, WORD wAmountFlashBlocks, WORD wCurrentBlock ); /** * Callbackfunction for MobileSwTransmissionStart. * This callbackfunction is called from SWUPLIB at the beginning of the update-process. * If the application wants to show the percentage of completion, it must * save the value given by ulBytesToTransfer for later comparison of the actual value * ( given via MobileSwTransmissionProgressCallBack() ) with the stored value. * * \param wUpdateNr First Parameter is the Update-Nr * \param ulBytesToTransfer Second Parameter is the amount of data to be sent * \return void * * \ingroup swupfun */ typedef void ( * MobileSwTransmissionStartCallBack ) ( WORD wUpdateNr, unsigned long ulBytesToTransfer ); /** * Callbackfunction for MobileSwTransmissionProgress. * This callbackfunction is called from SWUPLIB during the update-process to give * the user of the Library the possibility to show the current * transmission-progress. Compare the given value against the value given by callbackfunction * MobileSwTransmissionStartCallBack() to show the percentage of data beeing transmitted. * * \param wUpdateNr First Parameter is the Update-Nr * \param ulBytesTransfered Second Parameter is the current amount of sent data * \return void * * \ingroup swupfun */ typedef void ( * MobileSwTransmissionProgressCallBack ) ( WORD wUpdateNr, unsigned long ulBytesTransfered ); /** * Callbackfunction for SoftwareUpdateSuccess. * This Callbackfunction is called from inside the SWUPLIB if the complete update * was successfull. * * \param wUpdateNr First Parameter is the Update-Nr * \return void * * \ingroup swupfun */ typedef void ( * MobileSwUpdateSuccessCallBack ) ( WORD wUpdateNr ); /** * Callbackfunction for SoftwareUpdateError. * This Callbackfunction is called from inside the SWUPLIB if an error occured * inside the Library. Call WSwup_GetLastErrorString() to retrieve an error-description. * * \param wUpdateNr First Parameter is the Update-Nr * \return void * * \ingroup swupfun */ typedef void ( * MobileSwUpdateErrorCallBack ) ( WORD wUpdateNr ); /** * Possible Errors on Consistence-Check between Mobile and New SW ( combined via or ) * */ #define CONSISTENCE_PRODUCT_ERROR 0x01 /**< SW and Mobile are different products \ingroup swupfun */ #define CONSISTENCE_SWVERSION_ERROR 0x02 /**< Mobile has newer SVN than the new SW \ingroup swupfun */ #define CONSISTENCE_SWDATE_ERROR 0x04 /**< Mobile has newer SW-Date than the new SW \ingroup swupfun */ /** * Callbackfunction for SoftwareUpdateConsistence-Problem. * This function is called by the SWUPLIB if there is a consistence-error between * the new SW and the SW that is already in Mobile. The user of the LIB can use * the parameters to show the enduser the conflict and let the enduser choose a solution. * Depending on this choice the returnvalue of this function must be set to TRUE or FALSE. * * \param wUpdateNr First Parameter is the Update-Nr * \param pMobileInfo Second Parameter is a pointer to a struct containing the mobile-information * \param pNewSwInfo Third Parameter is a pointer to a struct containing the new-sw-information * \param wErrorComposition Fourth Parameter is a composition of the different error-possibilities * * \retval TRUE -> must be set to TRUE by the user of the LIB , if SW-Update is allowed * \retval FALSE -> must be set to FALSE by the user of the LIB , if SW-Update is NOT allowed * * \ingroup swupfun * */ typedef BOOL ( * MobileSwUpdateConsistenceProblemCallBack ) ( WORD wUpdateNr, t_SwInformation * pMobileInfo, t_SwInformation * pNewSwInfo, WORD wErrorComposition ); /* ------------------------------------------------------------------------ * WSwup_InstallSoftwareUpdateCallBackFunctions * ------------------------------------------------------------------------ */ /** * Installs all the needed callbackfunctions for the whole software-update * * \param pfnBootstrapProgress -> Pointer to a CallbackRoutine that is called on Bootstrap * \param pfnUpdateSwTransmissionStart -> Pointer to a CallbackRoutine that is called on UpdateSwTransmissionStart * \param pfnUpdateSwTransmissionProgress -> Pointer to a CallbackRoutine that is called during UpdateSwTransmission * \param pfnFlashType -> Pointer to a CallbackRoutine that is called for Flash-Type * \param pfnEraseProgress -> Pointer to a CallbackRoutine that is called on during Erasure of Flash * \param pfnMobileSwTransmissionStart -> Pointer to a CallbackRoutine that is called on Start of MobileSw-Transmission * \param pfnMobileSwTransmissionProgress -> Pointer to a CallbackRoutine that is called during Progress of MobileSw-Transmission * \param pfnMobileSwUpdateSuccess -> Pointer to a CallbackRoutine that is called if SW-Update was successfull * \param pfnMobileSwUpdateError -> Pointer to a CallbackRoutine that is called if SW-Update had an error * \param pfnMobileConsistenceProblem -> Pointer to a CallbackRoutine that is called if there is a consistence-problem * \return void * * \ingroup swupfun * */ void SWUPLIBDLLEXIMPORT WSwup_InstallSoftwareUpdateCallBackFunctions( BootstrapProgressCallBack pfnBootstrapProgress, UpdateSwTransmissionStartCallBack pfnUpdateSwTransmissionStart, UpdateSwTransmissionProgressCallBack pfnUpdateSwTransmissionProgress, FlashTypeCallBack pfnFlashType, EraseProgressCallBack pfnEraseProgress, MobileSwTransmissionStartCallBack pfnMobileSwTransmissionStart, MobileSwTransmissionProgressCallBack pfnMobileSwTransmissionProgress, MobileSwUpdateSuccessCallBack pfnMobileSwUpdateSuccess, MobileSwUpdateErrorCallBack pfnMobileSwUpdateError, MobileSwUpdateConsistenceProblemCallBack pfnMobileConsistenceProblem ); /** * Callback-Time for MobileSwUpdateInfoCallBack() * \ingroup swupfun */ typedef enum { enInfoCallBackEarlyWithBfc, /**< Callback will be called when Mobile is normal switched on => no timeouts */ enInfoCallBackLateDuringUpdate /**< Callback will be called when mobile is already in update-mode => deal with pc-timeouts ! */ } t_InfoCallBackTime; /** * Callbackfunction for SoftwareUpdateInfo. * This function is called by the SWUPLIB independent of and before any consistence-errors * if the callbackfunction is installed via function : WSwup_InstallSoftwareInfoCallBackFunction(). * This means: If you want to get info about the SW already in Mobile, then you have to install * this callbackfuntion. If you want to allow the SW-Update, you must return TRUE to the library. * But be prepared: If the library itself detects a conflict between new and old SW, * the callbackfunction MobileSwUpdateConsistenceProblemCallBack() * will be called, independant of the call of this callbackfunction ! * If you want to "deinstall" a previosly registered callbackfunction, call function * WSwup_InstallSoftwareInfoCallBackFunction() with a NULL-Parameter.
* Attention: If you return FALSE with this callback-function, the Update will be stopped, * but neither MobileSwUpdateSuccessCallBack() nor MobileSwUpdateErrorCallBack() will be called, * because the library does not know the reason why you stopped the update !
* This means you have to generate and show an error to enduser by yourself ! * * * \param wUpdateNr First Parameter is the Update-Nr * \param pMobileInfo Second Parameter is a pointer to a struct containing the mobile-information * \param pNewSwInfo Third Parameter is a pointer to a struct containing the new-sw-information * * \retval TRUE -> must be set to TRUE by the user of the LIB , if SW-Update is allowed * \retval FALSE -> must be set to FALSE by the user of the LIB , if SW-Update is NOT allowed * * \ingroup swupfun * */ typedef BOOL ( * MobileSwUpdateInfoCallBack ) ( WORD wUpdateNr, t_SwInformation * pMobileInfo, t_SwInformation * pNewSwInfo ); /* ------------------------------------------------------------------------ * WSwup_InstallSoftwareInfoCallBackFunction * ------------------------------------------------------------------------ */ /** * Installs the MobileSwUpdateInfoCallBack-Function. * * \param pfnMobileSwUpdateInfoCallBack -> Pointer to a CallbackRoutine that is called to give info about the SW already in Mobile
* pass a NULL if you want to deinstall a previosly installed callbackfunction.
* This is the only place in the LIB where NULL as func-ptr is allowed in the moment ! * \param WhichCallbackTime -> a enum of type \ref t_InfoCallBackTime , where you must select, on which time you want this * callbackfunction called. There are two possibilities , either you can have this function called during * connection-setup with BFC-Communication or you can select to have this function called later, when * update is already running.
* The reason to have these two different times is : on the one hand you have to deal with timeouts * when already really in updatemode, this leads to the early test. On the other hand the early test is less * "hacker-proof" because the mobile is in a totally different mode and there is at least a very little chance to * exchange two mobiles between the two mobile-states. So its up to the user of the library at which time he wants * the CallBack-Function. * * \return void * * \ingroup swupfun * */ void SWUPLIBDLLEXIMPORT WSwup_InstallSoftwareInfoCallBackFunction( MobileSwUpdateInfoCallBack pfnMobileSwUpdateInfoCallBack, t_InfoCallBackTime WhichCallbackTime ); /** * Behaviour of the Library concerning the new Update-Concept ( xx45 ). * */ typedef enum { enForceBSLBehaviour, /**< force old ( Boot-Strap-Loader ) behaviour, only for development possible, not for customer */ enForceNewConcept, /**< force new Update-Concept-Behaviour , must be used for customer-update */ enUpdateConceptAutoDetect /**< first try new concept, if mobile doesnt answer, try old BSL-concept, only for development possible, not for customer */ }t_UpdateMode; /* ------------------------------------------------------------------------ * WSwup_SetUpdateConceptMode * ------------------------------------------------------------------------ */ /** * Tells the library how to perform the Software-Update. * In a development-environment it must be still possible do use the old BSL-behaviour, but for * a customer-update its necessary to switch to the new update-mode. * For development environment it's also possible to do an autodetect, first the new concept is tried * and if this fails ( e.x. because its an old project ) then the old BSL-Mode is activated. * If you want to use the new mode ( enForceNewConcept, enAutoDetect ) you MUST call this function * before WSwup_CheckUpdateVoltage() and you also MUST call function WSwup_CheckUpdateVoltage() ! * * \param WhichMode an \ref t_UpdateMode , which tells the library how to behave * * \retval TRUE -> everything prepared * \retval FALSE -> * * \ingroup swupfun * */ BOOL SWUPLIBDLLEXIMPORT WSwup_SetUpdateConceptMode( t_UpdateMode WhichMode ); /* ------------------------------------------------------------------------ * WSwup_PerformSoftwareUpdate * ------------------------------------------------------------------------ */ /** * Performs the Software-Update on the given ComPort with the given Baudrate. * Attention: this function creates a thread, so the function itself will * terminate very fast, so that further things can be done. * The communication with the main-program will be done via the above CallbackFunctions * * * \param wUpdateNr The current number for the update, up to four are allowed * \param WhichCom The Comport on which the update shall be progressed * \param ulSpeed the max speed that can be driven on this PC , ( use ADDIDATA-Baudrates even if * you have a fastboot-card installed, the mapping is done internally via the INI-FILE * * \retval TRUE -> SW-Update is Running ( not finished ! ) * \retval FALSE -> No Callbacks Installed * * \ingroup swupfun * */ BOOL SWUPLIBDLLEXIMPORT WSwup_PerformSoftwareUpdate( WORD wUpdateNr, t_SwupCom WhichCom, unsigned long ulSpeed ); /* ------------------------------------------------------------------------ * WSwup_SetBootPIN * ------------------------------------------------------------------------ */ /** * Save a PIN for an Update, This PIN must be provided by data stored in PICS * and is sended during BSL connect attempt. This PIN is used for disabled BSL * mode devices. If the PIN is correct the mobile will accept the update sw. * A PIN can be reseted by calling this function with unPinSize==0 or * pucBootPIN==NULL * * \param wUpdateNr The current number for the update, up to four are allowed * \param unPinSize Number of data bytes of Boot PIN (16 Byte(128Bit) in the moment) * \param pucBootPIN Pointer to PIN Data * * * \retval TRUE -> PIN was set /reseted * \retval FALSE -> unPINSize or wUpdateNr data to large/ not supported * * \ingroup swupfun * */ BOOL SWUPLIBDLLEXIMPORT WSwup_SetBootPIN(WORD wUpdateNr, unsigned int unPinSize, unsigned char * pucBootPIN); #endif // _SWUPLIB_HEADER_