This is an old revision of the document!
ezFIT Optimizer (for Clarujust) API
Following is the Application Programming Interface (API) for the ezFIT Optimizer application.
API 1.27
This API is based on 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: Integer; safecall; end;
API 1.0
This API is based on the original 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 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 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 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 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 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 and 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 and 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.
GetAudiogram(out AnAudiogram: PSafeArray; EarSideIdx: Integer): ErrorCode
Get the audiogram for the specified ear side.
Return ErrorCode: 0 if successful, non-zero if not.
SetSerialNumber(SerialNum: PChar; EarSideIdx: Integer)
Set the serial number for the specified ear side.
See 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 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 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 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 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 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 Tubing Type and 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 Tubing Type and 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()
.
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()
, 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()
, 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 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 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(): 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.
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
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 |
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#:
//---------------------------------------------------------------------------------------------------------- /// <summary> /// Gets serial number string from the ezFIT Optimizer framework, which is provided as a safearray. /// </summary> /// <param name="ASerialNumber">Serial Number string.</param> /// <param name="EarSideIdx">Ear Side index to query.</param> /// <param name="fwk">ezFit optimizer framework interface.</param> /// <returns>Error code: 0 if successful, non-zero if not.</returns> //---------------------------------------------------------------------------------------------------------- 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#:
//---------------------------------------------------------------------------------------------------------- /// <summary> /// Gets device ID string from the ezFIT Optimizer framework, which is provided as a safearray. /// </summary> /// <param name="ADeviceID">Device ID string.</param> /// <param name="EarSideIdx">Ear Side index to query.</param> /// <param name="fwk">ezFit optimizer framework interface.</param> /// <returns>Error code: 0 if successful, non-zero if not.</returns> //---------------------------------------------------------------------------------------------------------- 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; }