== ezFIT Optimizer (for Clarujust) API == Following is the Application Programming Interface (API) for the ezFIT Optimizer application. === API 1.28 === This API is based on [[ezfit:clarujust:ezorange_api|ezOrange API 3.6]]: IEzFITOptimizerClarujust = interface(IDispatch) ['{1ACEAB90-8E9A-43E7-B670-0DC23B3F4825}'] function SetEar(EarSideIdx: Integer): Integer; safecall; function GetEar: Integer; safecall; function SetMemory(MemIdx: Integer): Integer; safecall; function GetMemory: Integer; safecall; function SetInterface(ProgIntfIdx: Integer): Integer; safecall; function GetInterface(out ProgIntfIdx: Integer): Integer; safecall; function SetHAInitialize: Integer; safecall; function SetHARead: Integer; safecall; function SetHAWrite: Integer; safecall; function SetHABurn: Integer; safecall; function SetHAClose: Integer; safecall; function GetHAInitialized(out IsInitialized: WordBool): Integer; safecall; function SetBumpQ(BumpQIdx: Integer): Integer; safecall; function GetBumpQ(out BumpQIdx: Integer; out BumpQVal: Single): Integer; safecall; function SetBumpGain(BumpGainIdx: Integer): Integer; safecall; function GetBumpGain(out BumpGainIdx: Integer; out BumpGainVal: Single): Integer; safecall; function SetBumpCF(BumpCFIdx: Integer): Integer; safecall; function GetBumpCF(out BumpCFIdx: Integer; out BumpCFVal: Single): Integer; safecall; function SetTiltCF(TiltCFIdx: Integer): Integer; safecall; function GetTiltCF(out TiltCFIdx: Integer; out TiltCFVal: Single): Integer; safecall; function SetTiltSlope(TiltSlopeIdx: Integer): Integer; safecall; function GetTiltSlope(out TiltSlopeIdx: Integer; out TiltSlopeVal: Single): Integer; safecall; function SetGain(GainIdx: Integer): Integer; safecall; function GetGain(out GainIdx: Integer; out GainVal: Single): Integer; safecall; function SetBias(BiasIdx: Integer): Integer; safecall; function GetBias(out Bias: Integer): Integer; safecall; function SetSilentErrors(Silent: WordBool): Integer; safecall; function GetSilentErrors: WordBool; safecall; procedure GetEthosArray(out Arr: PSafeArray; EarSideIdx: Integer); safecall; function SetCompression(BumpGain60: Integer; BumpQ60: Integer; BumpCF60: Integer; TiltSlope60: Integer; OverallGain60: Integer; GainBias60: Integer; BumpGain80: Integer; BumpQ80: Integer; BumpCF80: Integer; TiltSlope80: Integer; OverallGain80: Integer; GainBias80: Integer): Integer; safecall; procedure LaunchClarujustApp(AppType: Integer); safecall; procedure SetParams(Params: OleVariant; EarSideIdx: Integer); safecall; function GetParams(EarSideIdx: Integer): OleVariant; safecall; function SetAudiogram(AnAudiogram: PSafeArray; EarSideIdx: Integer): Integer; safecall; function GetAudiogram(out AnAudiogram: PSafeArray; EarSideIdx: Integer): Integer; safecall; procedure SetSerialNumber(SerialNum: PChar; EarSideIdx: Integer); safecall; function GetSerialNumber(out SerialNum: PChar; EarSideIdx: Integer): Integer; safecall; procedure SetManufLibrary(ANzBase: OleVariant); safecall; function UnitTest(ProgIntfIdx: Integer; MemIdx: Integer; SelMem1: WordBool; SelMem2: WordBool; SelMem3: WordBool; SelMem4: WordBool): Integer; safecall; function ApplySettings: Integer; safecall; function Setup60: Integer; safecall; function Setup80: Integer; safecall; function SetEarCount(EarCount: Integer): Integer; safecall; function GetEarCount(out EarCount: Integer): Integer; safecall; function isOptimizationDone: WordBool; safecall; procedure AllowProgInterfaceInit(AllowInit: WordBool); safecall; function GetVersion: Double; safecall; function GetBuildNumber: Integer; safecall; procedure SetSelectedMemories(Memory1: WordBool; Memory2: WordBool; Memory3: WordBool; Memory4: WordBool); safecall; procedure GetSelectedMemories(out Memory1: WordBool; out Memory2: WordBool; out Memory3: WordBool; out Memory4: WordBool); safecall; procedure SetDeviceID(ID: PChar; EarSideIdx: Integer); safecall; function GetDeviceID(out ID: PChar; EarSideIdx: Integer): Integer; safecall; function SetTubingType(TubingTypeIdx: Integer; EarSideIdx: Integer): Integer; safecall; function GetTubingType(out TubingTypeIdx: Integer; EarSideIdx: Integer): Integer; safecall; function GetSerialNumberSafeArray(out ASerialNum: PSafeArray; EarSideIdx: Integer): Integer; safecall; function GetDeviceIDSafeArray(out ADeviceID: PSafeArray; EarSideIdx: Integer): Integer; safecall; function GetBaseline(BaselineIdx: Integer; EarSideIdx: Integer): PSafeArray; safecall; function GetOutputParams(BaselineIdx: Integer): PSafeArray; safecall; function GetSessionRunTime: Integer; safecall; function ApplyOptimizations(WriteToCircuit: WordBool): Integer; safecall; procedure GetProductCode(out AProductCode: PChar; EarSideIdx: Integer); safecall; end; === API 1.0 === This API is based on the original [[ezfit:clarujust:ezorange_api|ezOrange API 3.4]]: NOTE: Any parameter with ''var'' or ''out'' in front of it means it is a call by reference. Not Available Original [[ezfit:clarujust:ezorange_api|ezOrange API 3.5]], for reference purposes: Public Function SetEar(ByVal index As Integer) As Integer Public Function GetEar() As Integer Public Function SetMemory(ByVal index As Integer) As Integer Public Function GetMemory() As Integer Public Function SetInterface(ByVal index As Integer) As Integer Public Function GetInterface() As Integer Public Function SetHAIntialize() As Integer Public Function SetHARead() As Integer Public Function SetHAWrite() As Integer Public Function SetHABurn() As Integer Public Function SetHAClose() As Integer Public Function GetHAIntialized() As Boolean Public Function SetBumpQ(ByVal index As Integer) As Integer Public Function GetBumpQ(ByRef Value as Single) As Integer Public Function SetBumpGain(ByVal index As Integer) As Integer Public Function GetBumpGain(ByRef Value as Single) As Integer Public Function SetBumpCF(ByVal index As Integer) As Integer Public Function GetBumpCF(ByRef Value as Single) As Integer Public Function SetTiltCF(ByVal index As Integer) As Integer Public Function GetTiltCF(ByRef Value as Single) As Integer Public Function SetTiltSlope(ByVal index As Integer) As Integer Public Function GetTiltSlope(ByRef Value as Single) As Integer Public Function SetGain(ByVal index As Integer) As Integer Public Function GetGain(ByRef Value as Single) As Integer Public Function SetBias(Bias As Integer) As Integer Public Function GetBias(Bias As Integer) As Integer Public Function SetSilentErrors(ByVal Silent As Boolean) As Integer Public Function GetSilentErrors() As Boolean Public Sub GetEthosArray(arr() As Long) Public Function SetCompression( ByVal BumpGain60 As Integer, ByVal BumpQ60 As Integer, ByVal BumpCF60 As Integer, ByVal TiltSlope60 As Integer, ByVal OverallGain60 As Integer, ByVal Bias60 as integer ByVal BumpGain80 As Integer, ByVal BumpQ80 As Integer, ByVal BumpCF80 As Integer, ByVal TiltSlope80 As Integer, ByVal OverallGain80 As Integer ByVal GainBias80 as Integer ) As Integer Public Function SetParams(Arr: OleVariant); Public Function GetParams(): OleVariant; Public Function SetAudiogram(Audiogram: PSafeArray); Public Function GetAudiogram(): PSafearray; Public Function SetSerialNum(SerialNum: string); Public Function GetSerialNum(): string; Public Function SetShowForm(ByVal Visible As Boolean) As Integer Public Function GetShowForm() As Boolean == Abstract Data Types == === SetEar(EarSideIdx: Integer): ErrorCode === Set ear side for Optimizer. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetEar(): ErrorCode === Get the current ear side for Optimizer. Return ErrorCode: 0 for Left Ear side, or 1 for Right Ear side. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === SetMemory(MemIdx: Integer): ErrorCode === Set the current working memory for the instrument. Return ErrorCode: 0 if successful, non-zero if not. === GetMemory(): MemoryIdx === Get the current working memory for the instrument. === SetInterface(ProgIntfIdx: Integer): ErrorCode === Set the programming interface to use. If an invalid programming interface is provided, it defaults to HiPro. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#programming_interface|Programming Interface]] data type. === GetInterface(out ProgIntfIdx: Integer): ErrorCode === Get the programming interface being used. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#programming_interface|Programming Interface]] data type. === SetHAInitialize(): ErrorCode === Initialize the hearing instrument. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetHARead(): ErrorCode === Read the parameters from the hearing instrument. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetHAWrite(): ErrorCode === Write the parameters in Optimizer to the hearing instrument. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetHABurn(): ErrorCode === Burn the parameters in Optimizer to instrument's circuit EEPROM. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetHAClose(): ErrorCode === Close communication with hearing instrument. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetHAInitialized(out IsInitialized: WordBool): ErrorCode === Get hearing instrument initialization status. ''IsInitialized'' is ''True'' if instrument was initialized, ''False'' if not. Return ErrorCode: 0 if successful, non-zero if not. === SetBumpQ(BumpQIdx: Integer): ErrorCode === Set Bump Quality to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetBumpQ(out BumpQIdx: Integer; out BumpQVal: Single): ErrorCode === Get the Bump Quality index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetBumpGain(BumpGainIdx: Integer): ErrorCode === Set the Bump Gain to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetBumpGain(out BumpGainIdx: Integer; out BumpGainVal: Single): ErrorCode === Get the Bump Gain index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetBumpCF(BumpCFIdx: Integer): ErrorCode === Set the Bump Center Frequency to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetBumpCF(out BumpCFIdx: Integer; out BumpCFVal: Single): ErrorCode === Get the Bump Center Frequency index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetTiltCF(TiltCFIdx: Integer): ErrorCode === Set the Tilt Center Frequency to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetTiltCF(out TiltCFIdx: Integer; out TiltCFVal: Single): ErrorCode === Get the Tilt Center Frequency index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetTiltSlope(TiltSlopeIdx: Integer): ErrorCode === Set the Tilt Slope to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetTiltSlope(out TiltSlopeIdx: Integer; out TiltSlopeVal: Single): ErrorCode === Get the Tilt Slope index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetGain(GainIdx: Integer): ErrorCode === Set the Overall Gain to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetGain(out GainIdx: Integer; out GainVal: Single): ErrorCode === Get the Overall Gain index and value. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetBias(BiasIdx: Integer): ErrorCode === Set the Bias to the specified index. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === GetBias(out Bias: Integer): ErrorCode === Get the Bias value (same index). This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === SetSilentErrors(Silent: WordBool): ErrorCode === Set Silent Error reporting On or Off. Set ''Silent'' to ''True'' if On, ''False'' if Off. Return ErrorCode: 0 if successful, non-zero if not. The reporting is written to a log file ''ezFITOptimizerSvr.log'' in the same folder as the calling application. === GetSilentErrors: WordBool === Get status (On or Off) of Silent Error reporting. Return Status: ''True'' if On, ''False'' if Off. === GetEthosArray(out Arr: PSafeArray; EarSideIdx: Integer) === Get an array with Ethos parameters for the specified ear side. === SetCompression(...) === function SetCompression(BumpGain60: Integer; BumpQ60: Integer; BumpCF60: Integer; TiltSlope60: Integer; OverallGain60: Integer; GainBias60: Integer; BumpGain80: Integer; BumpQ80: Integer; BumpCF80: Integer; TiltSlope80: Integer; OverallGain80: Integer; GainBias80: Integer): ErrorCode Set the Compression Ratio for base line 60 and base line 80, given their respective Bump, Tilt, Gain, and Bias. This routine affect both ear sides. Return ErrorCode: 0 if successful, non-zero if not. === LaunchClarujustApp(AppType: Integer) === Launch the Clarujust application. This application opens a modal window. ''AppType'' specifies what application to call: * 0 = ClarujustApp: This is the target application to run. * 1 = ClarujustLiteApp: This application is for testing and debugging purposes. === SetParams(Params: OleVariant; EarSideIdx: Integer) === Set circuit parameters (array in an OleVariant container) for the specified ear side. See [[#circuit_parameters|Circuit Parameters]] and [[#ear_side|Ear Side]] data types. === GetParams(EarSideIdx: Integer): OleVariant === Get circuit parameters from the specified ear side. Return circuit parameter array (as OleVariant). See [[#circuit_parameters|Circuit Parameters]] and [[#ear_side|Ear Side]] data types. === SetAudiogram(AnAudiogram: PSafeArray; EarSideIdx: Integer): ErrorCode === Set the audiogram for the specified ear side. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#audiogram|Audiogram]] and [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data types. === GetAudiogram(out AnAudiogram: PSafeArray; EarSideIdx: Integer): ErrorCode === Get the audiogram for the specified ear side. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#audiogram|Audiogram]] and [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data types. === SetSerialNumber(SerialNum: PChar; EarSideIdx: Integer) === Set the serial number for the specified ear side. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetSerialNumber(out SerialNum: PChar; EarSideIdx: Integer): ErrorCode === Get the serial number for the specified ear side. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetSerialNumberSafeArray(out SerialNum: PSafeArray; EarSideIdx: Integer): ErrorCode === Get the serial number for the specified ear side. Use this method instead, for environments in which using ''GetSerialNumber()'' does not work correctly (eg. Windows 7). Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === SetDeviceID(DeviceID: PChar; EarSideIdx: Integer) === Set the globally unique device ID for the specified ear side. This ID is dependent on the patient name and product being used. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetDeviceID(out DeviceID: PChar; EarSideIdx: Integer): ErrorCode === Get the globally unique device ID for the specified ear side. This ID is dependent on the patient name and product being used. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetDeviceIDSafeArray(out DeviceID: PSafeArray; EarSideIdx: Integer): ErrorCode === Get the globally unique device ID for the specified ear side. This ID is dependent on the patient name and product being used. Use this method instead, for environments in which using ''GetDeviceID()'' does not work correctly (eg. Windows 7). Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === SetTubingType(TubingTypeIdx: integer; EarSideIdx: Integer): ErrCode === Set the tubing type for the specified ear side. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#tubing_type|Tubing Type]] and [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === GetTubingType(out TubingTypeIdx: integer; EarSideIdx: Integer): ErrorCode === Get the tubing type for the specified ear side. This value could be one of the following: Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#tubing_type|Tubing Type]] and [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. === SetManufLibrary(ANzBase: OleVariant) === Set the circuit manufacturer library to use for calling circuit I/O routines. === UnitTest(...) === UnitTest(ProgIntfIdx: Integer; MemIdx: Integer; SelMem1: WordBool; SelMem2: WordBool; SelMem3: WordBool; SelMem4: WordBool): ErrorCode Perform unit testing for the library. Only used during debugging. === ApplySettings(): ErrorCode === Calculate new circuit parameters, and write them to the circuit RAM, then burn them to the circuit's EEPROM. This routine affects both ears (if performing binaural fit). This is usually called after: * Setting Bump, Tilt, and Gain. * Calling ''[[#setcompression| SetCompression()]]''. Return ErrorCode: 0 if successful, non-zero if not. === Setup60(): ErrorCode === Set Optimizer BaseLine to 60. This method will: * Reset Bump, Tilt, and Gain. * Calculate the equalizer baseline 60. * Call ''[[#applysettings_errorcode|ApplySettings()]]'', which affects both ears (if performing binaural fit). All Bump, Tilt, Gain, and Bias calculations will be based on base line 60 after this. Return ErrorCode: 0 if successful, non-zero if not. This routine affect both ear sides. === Setup80(): ErrorCode === Set Optimizer BaseLine to 80. This method will: * Reset Bump, Tilt, and Gain. * Calculate the equalizer baseline 80. * Call ''[[#applysettings_errorcode|ApplySettings()]]'', which affects both ears (if performing binaural fit). All Bump, Tilt, Gain, and Bias calculations will be based on base line 80 after this. Return ErrorCode: 0 if successful, non-zero if not. This routine affect both ear sides. === SetEarCount(EarCount: Integer): ErrorCode === Set the ear count. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_count|Ear Count]] data type. NOTE: There is no need to call ''SetEarCount()'' since the ''SetHAInitialize()'' will detect the correct ear count. === GetEarCount(out EarCount: Integer): ErrorCode === Get the ear count. Return ErrorCode: 0 if successful, non-zero if not. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_count|Ear Count]] data type. === isOptimizationDone(): WordBool === Get status of whether optimization process has been completed. This flag gets reset to ''False'' every time the routine ''SetHAInitialize()'' gets called. Returns ''True'' if optimization was completed, ''False'' if not. === ApplyOptimizations(WriteToCircuit: WordBool): ErrorCode === Apply any independent optimizations to the circuit and selected memories. This lets the optimizer know that all the work is done, and it would be typically called just before disconnecting from the optimizer server. The boolean parameter ''WriteToCircuit'' enables or disables the writing of parameters to the circuit. Return ErrorCode: 0 if successful, non-zero if not. === AllowProgInterfaceInit(AllowInit: WordBool) === Set flag to allow Programmer Interface to be initialized during circuit detection in ''SetHAInitialize()''. By default, this flag is ''False'', so ''SetHAInitialize()'' will only detect for a circuit assuming the programming interface has been initialized and opened already. === GetVersion(): Double === Get the Optimizer Server DLL version. The format is a floating point number matching the current API version version. Eg.: if the API is 1.21, the version is 1.21 as well. === GetBuildNumber(): Integer === Get the Optimizer Server DLL Build Number. The format is ''YYYYMMDDSS'' where Y = Year, M = Month, D = Day, and S = Serial for current day. Eg.: 2010012201 (Y = 2010, M = 01, D = 22, S = 01). === SetSelectedMemories(Memory1, Memory2, Memory3, Memory4: WordBool) === Set the selected memories to which the Clarujust final settings must be applied to. Basically, these are the memories that must be autofitted with the Clarujust optimizations. === GetSelectedMemories(out Memory1, Memory2, Memory3, Memory4: WordBool) === Get the selected memories to which the Clarujust final settings must be applied to. Basically, these are the memories that must be autofitted with the Clarujust optimizations. === GetBaseline(BaselineIdx: Integer; EarSideIdx: Integer): PSafeArray; === Get the specified baseline from the specified ear side. Return: Baseline in a SafeArray format. === GetOutputParams(BaselineIdx: Integer): PSafeArray; === Get the output parameters of the specified baseline (0=Baseline60, 1=Baseline80). Return: Output Parameters in a SafeArray format. === GetSessionRunTime(): Integer === Get the total number of seconds used during the optimization session. Return: TotalSeconds === GetProductCode(out AProductCode: PChar; EarSideIdx: Integer) === Get the globally unique product code for the specified ear side. This product code is dependent on the read instrument. See [[ezfit:clarujust:ezfit_optimizer_clarujust_api#product_codes|Product Codes]] and [[ezfit:clarujust:ezfit_optimizer_clarujust_api#ear_side|Ear Side]] data type. == Data Types & Ranges == ==== Programming Interface ==== Return or Set values for ''GetInterface()'' and ''SetInterface()'' routines: ^ Code ^ Value ^ Description ^ | 0 | Simulation | There is no programmer interface. | | 1 | HiPro | HiPro programmer interface. | | 2 | MicroCard | Microcard programmer interface. | | 3 | Gennum DSP | Gennum DSP programmer interface. Not supported. | | 4 | NOAHlink | NOAHlink programmer interface. Supported as of API 1.27 (20100816). | | 5 | CF2 | CF2 programmer interface. Not supported. | | 6 | EMiniTec | EMiniTec programmer interface. | ==== Ear Count ==== Return or Set values for ''GetEarCount()'' and ''SetEarCount()'' routines: ^ Code ^ Value ^ Description ^ | 0 | None | No instrument. | | 1 | Left | Left instrument. | | 2 | Right | Right instrument. | | 3 | Both | Both instruments. | NOTE: There is no need to call ''SetEarCount()'' since the ''SetHAInitialize()'' will detect the correct ear count. ==== Ear Side ==== Return or Set values for ''GetEar()'' and ''SetEar()'' routines: ^ Code ^ Value ^ Description ^ | 0 | Left | Left instrument. | | 1 | Right | Right instrument. | ==== Tubing Type ==== Return or Set values for ''GetTubingType()'' and ''SetTubingType()'' routines: This value could be one of the following: ^ Code ^ Value ^ Description ^ | 0 | Open | Open fit tubing. | | 1 | Closed-2cc | Closed 2-cc tubing. | | 2 | Closed-Simulated | Closed simulated tubing. | | 3 | Closed-BTE-Ear-Hook | Closed BTE Ear Hook. | ==== Audiogram ==== Audiogram array to pass to Optimizer (''SetAudiogram()'' and ''GetAudiogram()''): ^ Index ^ Frequency ^ | 0 | 250 | | 1 | 500 | | 2 | 750 | | 3 | 1000 | | 4 | 1500 | | 5 | 2000 | | 6 | 3000 | | 7 | 4000 | | 8 | 6000 | | 9 | 8000 | ==== Product Codes ==== Return values for ''GetProductCode()'' routines: This value could be one of the following: ^ Product Code ^ Product Name ^ Description ^ | prod_Flx | Flx | OTE. | | prod_Intuition12 | Intuition 12 | Custom. | | prod_Sparo12 | Sparo 12 | OTE. | | prod_Loon | Loon | OTE. PHSI: LeFIT 201 | | prod_Pluros | Pluros | OTE. PHSI: LeFIT 301 | ==== Circuit Parameters ==== For ''SetParams()'', ''GetParams()'', and ''GetEthosParams()'', array format for Ethos-based circuit: paramsArray[0] := BEQ1_gain; paramsArray[1] := BEQ2_gain; paramsArray[2] := BEQ3_gain; paramsArray[3] := BEQ4_gain; paramsArray[4] := BEQ5_gain; paramsArray[5] := BEQ6_gain; paramsArray[6] := BEQ7_gain; paramsArray[7] := BEQ8_gain; paramsArray[8] := BEQ9_gain; paramsArray[9] := BEQ10_gain; paramsArray[10] := BEQ11_gain; paramsArray[11] := BEQ12_gain; paramsArray[12] := C1_MPO; paramsArray[13] := C2_MPO; paramsArray[14] := C3_MPO; paramsArray[15] := C4_MPO; paramsArray[16] := C5_MPO; paramsArray[17] := C6_MPO; paramsArray[18] := C7_MPO; paramsArray[19] := C8_MPO; paramsArray[20] := C1_Ratio; paramsArray[21] := C2_Ratio; paramsArray[22] := C3_Ratio; paramsArray[23] := C4_Ratio; paramsArray[24] := C5_Ratio; paramsArray[25] := C6_Ratio; paramsArray[26] := C7_Ratio; paramsArray[27] := C8_Ratio; paramsArray[28] := C1_TK; paramsArray[29] := C2_TK; paramsArray[30] := C3_TK; paramsArray[31] := C4_TK; paramsArray[32] := C5_TK; paramsArray[33] := C6_TK; paramsArray[34] := C7_TK; paramsArray[35] := C8_TK; paramsArray[36] := FBC_Enable; paramsArray[37] := input_mux; paramsArray[38] := matrix_gain; paramsArray[39] := Noise_Reduction; paramsArray[40] := preamp_gain0; paramsArray[41] := preamp_gain1; paramsArray[42] := TimeConstants; ==== Circuit I/O Operation Error Values ==== ^ Error Value ^ Error Code ^ Error Description ^ | 0 | OK | Operation was successful. | | 1 | NoProgrammer | Valid programmer has not been set. | | 2 | NoInstrument | No or invalid hearing instrument (HI) connected. | | 3 | BadArgument | Bad Argument provided. Check one of these: - Invalid programming interface - Invalid platformID specified - Invalid program specified - Invalid channel specified - Invalid data in params or config structure - Page argument invalid | | 4 | NotInitialized | Programmer has not been initialized yet. | | 5 | NotRead | Not Read. | | 6 | ChecksumError | Invalid data received. | | 7 | InvalidVersion | Invalid parameter version passed in. | | 8 | ProgrammerError | Error occurred trying to initialize programmer. | | 9 | CMFError | Error during previous load. | | 10 | WrongInstrument | Invalid security ID of the connected device. | | 11 | BootError | Boot Error. | | 12 | NoNLDriver | Noahlink drivers have not been installed. | | 13 | NLInUse | Noahlink in use by another software package. | ==== Bump, Tilt, Gain & Bias ==== ^ Parameter ^ Data Type ^ Item Count ^ Index Range ^ Value Range ^ Comments ^ | Bump Gain | Single | 21 | -10..10 | -10..10 | | | Bump Q | Single | 21 | 0..20 | 0.5..2.0 | Bump Quality | | Bump CF | Single | 21 | 0..20 | 125..8000 | Bump Center Frequency | | Tilt | Single | 21 | -10..10 | -10..10 | Tilt Slope | | Gain (overall) | Single | 21 | -10..10 | -10..10 | | | Bias | Single | 21 | -10..10 | -10..10 | | Bump Q ^ Index ^ Value ^ | 0 | 0.50 | | 1 | 0.55 | | 2 | 0.60 | | 3 | 0.65 | | 4 | 0.70 | | 5 | 0.75 | | 6 | 0.80 | | 7 | 0.85 | | 8 | 0.90 | | 9 | 0.95 | | 10 | 1.00 | | 11 | 1.10 | | 12 | 1.20 | | 13 | 1.30 | | 14 | 1.40 | | 15 | 1.50 | | 16 | 1.60 | | 17 | 1.70 | | 18 | 1.80 | | 19 | 1.90 | | 20 | 2.00 | Bump CF ^ Index ^ Value ^ | 0 | 125 | | 1 | 154 | | 2 | 189 | | 3 | 233 | | 4 | 287 | | 5 | 354 | | 6 | 435 | | 7 | 536 | | 8 | 660 | | 9 | 812 | | 10 | 1000 | | 11 | 1231 | | 12 | 1516 | | 13 | 1866 | | 14 | 2297 | | 15 | 2828 | | 16 | 3482 | | 17 | 4287 | | 18 | 5278 | | 19 | 6498 | | 20 | 8000 | == Client Interaction with Optimizer Server == === Declaration === type TfrmMain = class(TForm) btnGetParams: TButton; btnSetParams: TButton; btnDone: TButton; btnConnectToSvr: TButton; edSerialNum: TEdit; btnGetSerialNum: TButton; lblSerialNum: TLabel; lblAudiogram: TLabel; edAudiogram: TEdit; btnAudiogram: TButton; procedure btnAudiogramClick(Sender: TObject); procedure FormDestroy(Sender: TObject); procedure FormCreate(Sender: TObject); procedure btnGetSerialNumClick(Sender: TObject); procedure btnConnectToSvrClick(Sender: TObject); procedure btnDoneClick(Sender: TObject); private { Private declarations } svr: IEzFITOptimizerClarujust; cookie: integer; procedure ConnectToOptimizerSvr; end; === Connecting to Server === //----------------------------------------------------------------------------- // description: Launch and connect to the Optimizer server. // parameters : Sender: TObject // return : None //----------------------------------------------------------------------------- procedure TfrmMain.btnConnectToSvrClick(Sender: TObject); begin ConnectToOptimizerSvr(); if Assigned(svr) then begin // update buttons btnSetParams.Enabled := True; btnGetParams.Enabled := True; btnGetSerialNum.Enabled := True; edSerialNum.Enabled := True; DebugStr('Optimizer launched successfully'); ShowMessage('Optimizer launched successfully.'); end else begin DebugStr('svr was not assigned.'); btnSetParams.Enabled := False; btnGetParams.Enabled := False; btnGetSerialNum.Enabled := False; edSerialNum.Enabled := False; DebugStr('Optimizer FAILED to launch'); ShowMessage('Optimizer FAILED to launch.'); end; end; //----------------------------------------------------------------------------- // description: Connect to optimizer server. // parameters : None // return : None //----------------------------------------------------------------------------- procedure TfrmMain.ConnectToOptimizerSvr; var Unknown: IInterface; begin //--- Single server instance ------------------------------------ if not Assigned(svr) then begin // Check if server object is registered with Running Object Table (ROT). // Use the existing object instance, or create a new one of it does not exist. if (GetActiveObject(EzFITOptimizerSvr_TLB.Class_EzFITOptimizerClarujust, nil, Unknown) = MK_E_UNAVAILABLE) then begin DebugStr('ConnectToOptimizerSvr(): Create svr object.'); svr := CoEzFITOptimizerClarujust.Create; // create a new one, since object does not exist in ROT // Operation: Register at startup of main (application) object in the // so-called Running Object Table (ROT). // Purpose: Instead of starting a new instance, an automation client // can connect to the running instance of the application using // the GetActiveObject() and QueryInterface() methods. DebugStr('ConnectToOptimizerSvr(): RegisterActiveObject in the Running Object Table (ROT).'); // register with Running Object Table (ROT) RegisterActiveObject(svr, Class_EzFITOptimizerClarujust, ACTIVEOBJECT_WEAK, cookie); // lock to prevent premature unloading CoLockObjectExternal(svr, true, {lock} true); DebugStr('ConnectToOptimizerSvr(): ROT entry (Cookie) = ' + IntToStr(cookie)); end else begin // use obj in ROT DebugStr('ConnectToOptimizerSvr(): Svr object found. Use existing svr object.'); Unknown.QueryInterface(EzFITOptimizerSvr_TLB.IID_IEzFITOptimizerClarujust, svr); end; end; end; === Disconnecting from Server === //----------------------------------------------------------------------------- // description: Close the application. // parameters : Sender: TObject // return : None //----------------------------------------------------------------------------- procedure TfrmMain.btnDoneClick(Sender: TObject); begin DisconnectFromOptimizerSvr(); Close; // close window end; procedure TfrmMain.FormDestroy(Sender: TObject); begin DisconnectFromOptimizerSvr(); end; //----------------------------------------------------------------------------- // description: Disconnect from the Optimizer server. // parameters : None // return : None //----------------------------------------------------------------------------- procedure TfrmMain.DisconnectFromOptimizerSvr(); var Unknown: Iunknown; begin if Assigned(svr) then begin // Unregister from the Running Object Table (ROT). if (GetActiveObject(EzFITOptimizerSvr_TLB.Class_EzFITOptimizerClarujust, nil, Unknown) <> MK_E_UNAVAILABLE) then begin DebugStr(format('DisconnectFromOptimizerSvr(): RevokeActiveObject from the Running Object Table (ROT) entry %d.', [cookie])); CoLockObjectExternal(svr, false {lock}, true); // unlock to allow unloading RevokeActiveObject(cookie, nil); // unregister from Running Object Table (ROT) CoDisconnectObject(svr, 0); DebugStr(format('DisconnectFromOptimizerSvr(): Disconnected from object svr.', [])); end; DebugStr('DisconnectFromOptimizerSvr(): Destroying svr.'); svr := nil; // destroy optimizer object end; {endif} end; === Performing Independent Optimizations === After the optimizer client (such as Clarujust) connects to the optimizer server, it can perform whatever optimizations or adjustments it requires on the circuit, without having to call the built-in optimizer routines. After all the work is done, the optimizer client needs to call the ''ApplyOptimizations()'' routine to let the optimizer server know it is done with optimizations, and to store the values in the correct memories. NOTE: The HiPro port is available to the optimizer client after connecting to the optimizer server, and it must be made available by the optimizer client before calling ''ApplyOptimizations()''. ConnectToOptimizerSvr(); if (svr != null) { //------------------------------------------ // Get Fitting Session Data //------------------------------------------ ... such as: svr.GetEarCount(cnt); ear = svr.GetEar(); svr.GetInterface(idxIntf); svr.GetTubingType(idxTubing, sideLeft); svr.GetSerialNumber(SerialNumLeft, sideLeft); svr.GetSerialNumber(SerialNumRight, sideRight); svr.GetDeviceID(DeviceIDLeft, sideLeft); svr.GetDeviceID(DeviceIDRight, sideRight); svr.GetAudiogram(...); ... //-------------------------------------------------------------- // Do work: independent optimizations or circuit param changes //-------------------------------------------------------------- ... //-------------------------------------------------------------- // Finalize settings based on preferred optimizations //-------------------------------------------------------------- svr.ApplyOptimizations(); // will change both hearing instruments } DisconnectFromOptimizerSvr(); === Performing Test Sequences (Calling Built-in Optimizations) === After the optimizer client (such as Clarujust) connects to the optimizer server, it can call the built-in server routines. Outlined below is the process of calling these routines. Call ''Setup60()'' or ''Setup80()'' when preparing to run tests at one of those levels (Soft Sound tests at 60 dB, or Loud Sound tests at 80 dB, respectively). Calling either ''Setup60()'', or ''Setup80()'' calculates and applies the baseline settings derived from Autofit values. All Bump, Tilt, and Gain (as well as Bias) values are added to the appropriate baseline settings. These also reset the Bump, Tilt, and Gain parameters to a known state, thus ensuring everything runs smoothly. Furthermore, if some additional testing for soft sounds is required, for example, the procedure would be to call ''Setup60()'' followed by any initial values for Bump, Tilt and Gain. Then call ''ApplySettings()'' to have everything flow through. The additional delay incurred by ''Setup60()'' (or ''Setup80()'') automatically doing an ''ApplySettings()'', followed by another ''ApplySettings()'' after initializing settings is pretty small since it only happens once in a while. ''ApplySettings()'' can be called after updating each ear without causing a corruption of any data or settings. However, the communication with the hearing instrument will effectively be twice as long. Some of the methods automatically work on both ears (if present), while others require specifc selection of an ear. The following methods automatically affect both ears: * ''SetBumpG(...)'' * ''SetTiltSlope(...)'' * ''Setup60()'' * ''Setup80()'' * ''ApplySettings()'' Please note that previously, you had to call ''SetEar()'' before calling Set Bump/Tilt/Gain/Compression routines since they only affected a single ear. Now they apply settings to both sides all the time, so there is no need to call ''SetEar()'' anymore. The following flow would probably be something typical: ConnectToOptimizerSvr(); if (svr != null) { //------------------------------------------ // Get Fitting Session Data //------------------------------------------ ... such as: svr.GetEarCount(cnt); ear = svr.GetEar(); svr.GetInterface(idxIntf); svr.GetTubingType(idxTubing, sideLeft); svr.GetSerialNumber(SerialNumLeft, sideLeft); svr.GetSerialNumber(SerialNumRight, sideRight); svr.GetDeviceID(DeviceIDLeft, sideLeft); svr.GetDeviceID(DeviceIDRight, sideRight); GetAudiogram(); // both sides svr.GetEthosArray(ParamsLeft, sideLeft); svr.GetEthosArray(ParamsRight, sideRight); ... //----------------------------------- // Perform Soft Sound Test Groups //----------------------------------- // Set Baseline to 60 svr.Setup60(); Do { // Perform Test ... // Modify Bump, Tilt and Gain //svr.SetEar(left); // select an ear //svr.SetBumpG(...); //svr.SetTiltSlope(...); //... etc. //svr.SetEar(right); // select the other ear //svr.SetBumpG(...); //svr.SetTiltSlope(...); //... etc. svr.SetBumpG(...); svr.SetTiltSlope(...); ... etc. // Save settings to hearing instrument svr.ApplySettings(); // will change both HAs } repeat(until happy); //----------------------------------- // Perform Loud Sound Test Groups //----------------------------------- // Set Baseline to 80 svr.Setup80(); Do { // Perform Test ... // Modify Bump, Tilt and Gain //svr.SetEar(left); // select an ear //svr.SetBumpG(...); //svr.SetTiltSlope(...); //... etc. //svr.SetEar(right); // select the other ear //svr.SetBumpG(...); //svr.SetTiltSlope(...); //... etc. SetBumpG(...); SetTiltSlope(...); ... etc. // Save settings to hearing instrument svr.ApplySettings(); // will change both hearing instruments } repeat(until happy); //----------------------------------------------------- // Finalize settings based on preferred optimizations //----------------------------------------------------- //svr.SetEar(left); //svr.SetCompression(...); //svr.SetEar(right); //svr.SetCompression(...); svr.SetCompression(...); // will change both hearing instruments svr.ApplySettings(); // will change both hearing instruments } DisconnectFromOptimizerSvr(); === Getting Data === To get some data from the optimizer server, for example, the circuit Serial Number: //----------------------------------------------------------------------------- // description: OnClick for Get Serial Number button. // Get serial number from optimizer server. // parameters : Sender: TObject // return : None //----------------------------------------------------------------------------- procedure TfrmMain.btnGetSerialNumClick(Sender: TObject); var str: PChar; begin DebugStr('ClarujustAppLite: btnGetSerialNumClick()'); if Assigned(svr) then begin //str := svr.GetSerialNumber(); // API 1.0 or lower svr.GetSerialNumber(str, 1 {0=left, 1=right side}); // API 1.1 or higher edSerialNum.Text := str; DebugStr('ClarujustAppLite: SerialNum = ' + edSerialNum.Text); end; end; == Install & Uninstall Server & Client == To manually register the server DLL and client EXE, try the following from the command line: C:\> cd C:\Program Files\Audina\ezFITOptimizer C:\> regsvr32 EzFITOptimizerSvr.dll C:\> ClarujustAppLite /regserver To manually unregister the server DLL and client EXE, try the following from the command line: C:\> cd C:\Program Files\Audina\ezFITOptimizer C:\> regsvr32 /u EzFITOptimizerSvr.dll C:\> ClarujustAppLite /unregserver == Support Routines == === SafeArrayToIntArr() === //----------------------------------------------------------------------------- // description: Convert from SafeArray to integer array. // parameters : sfArr: PSafeArray // return : integer //----------------------------------------------------------------------------- function SafeArrayToIntArr(sfArr: PSafeArray): TIntegerArray; var i: integer; LBound, UBound: integer; Arr: TIntegerArray; ElemData: ShortInt; begin // alloc integer array with same size as safearray SafeArrayGetLBound(sfArr, 1, LBound); SafeArrayGetUBound(sfArr, 1, UBound); SetLength(arr, UBound+1); // copy data from safearray to integer array for i:= LBound to UBound do begin SafearrayGetElement(sfArr, i, ElemData); arr[i] := ElemData; // must use a shortint to get data out correctly end; result := Arr; end; === IntArrToPSafeArray() ==== //----------------------------------------------------------------------------- // description: Convert from integer array to SafeArray. // parameters : arr: array of integer; out sfArr: PSafeArray // return : None //----------------------------------------------------------------------------- procedure IntArrToPSafeArray(arr: array of integer; out sfArr: PSafeArray); var i: integer; LBound, HBound: integer; VarArr: Variant; begin LBound := Low(arr); HBound := High(arr); VarArr := VarArrayCreate( [LBound,HBound], varInteger{VT_INT}); // create variant array for i := Low(arr) to High(arr) do begin VarArr[i] := Arr[i]; // copy arr to variant array end; sfArr := PSafeArray(TVarData(VarArr).VArray); // convert variant arr to PSafeArray end; === VariantToData() ==== //----------------------------------------------------------------------------- // description: Convert a variant to a user-defined data type. // parameters : Value: Variant; Var Data; MaxByteCount: integer // return : None //----------------------------------------------------------------------------- procedure VariantToData(Value: Variant; var Data; MaxByteCount: integer); var p: pByte; len: integer; begin assert(MaxByteCount > 0); Try p := VarArrayLock(Value); Len := VarArrayHighBound(Value, 1) + 1; assert(Len <= MaxByteCount); move(p^, Data, Len-sizeof(integer)); finally VarArrayUnLock(Value); end; end; === DataToVariant() ==== //----------------------------------------------------------------------------- // description: Convert a user-defined data type to a variant. // parameters : const Data; MaxByteCount: integer // return : Variant //----------------------------------------------------------------------------- function DataToVariant(const Data; MaxLength: integer; AVarType: Word=varByte): Variant; var p: pByte; begin Result := VarArrayCreate([0, MaxLength-1], AVarType); p := VarArrayLock(Result); try move(Data, p^, MaxLength); finally VarArrayUnLock(Result); end; end; === GetSerialNumber() === Example code how to obtain the Serial Number using SafeArray when using C#: //---------------------------------------------------------------------------------------------------------- /// /// Gets serial number string from the ezFIT Optimizer framework, which is provided as a safearray. /// /// Serial Number string. /// Ear Side index to query. /// ezFit optimizer framework interface. /// Error code: 0 if successful, non-zero if not. //---------------------------------------------------------------------------------------------------------- private static int GetSerialNumber(out string ASerialNumber, int EarSideIdx, IEzFITOptimizerClarujust fwk) { Array RawSerialNumber; int error = 4; // not initialized ASerialNumber = string.Empty; if (fwk != null) { // get raw serial number (binary) error = fwk.GetSerialNumberSafeArray(out RawSerialNumber, 0); // extract serial number string StringBuilder str = new StringBuilder(); foreach (int c in RawSerialNumber) { str.Append(string.Format("{0}", (char)c)); } ASerialNumber = str.ToString(); ClarujustApp.LogMessage(String.Format("SerialNum[{0}] = {1} (ret code = {2}).", (EarSideIdx == 0 ? "L" : "R"), ASerialNumber, error)); } return error; } === GetDeviceID() === Example code how to obtain the Device ID using SafeArray when using C#: //---------------------------------------------------------------------------------------------------------- /// /// Gets device ID string from the ezFIT Optimizer framework, which is provided as a safearray. /// /// Device ID string. /// Ear Side index to query. /// ezFit optimizer framework interface. /// Error code: 0 if successful, non-zero if not. //---------------------------------------------------------------------------------------------------------- private static int GetDeviceID(out string ADeviceID, int EarSideIdx, IEzFITOptimizerClarujust fwk) { Array RawDeviceID; int error = 4; // not initialized ADeviceID = string.Empty; if (fwk != null) { // get raw serial number (binary) error = fwk.GetDeviceIDSafeArray(out RawDeviceID, 0); // extract serial number string StringBuilder str = new StringBuilder(); foreach (int c in RawDeviceID) { str.Append(string.Format("{0}", (char)c)); } ADeviceID = str.ToString(); ClarujustApp.LogMessage(String.Format("DeviceID[{0}] = {1} (ret code = {2}).", (EarSideIdx == 0 ? "L" : "R"), ADeviceID, error)); } return error; }