Search by Tags

OakLib 1.2 to 1.3 Migration Guide

 
Applicable for
oak

Article updated at 28 Oct 2017

Attention: this is a legacy library and thus not supported by Toradex anymore. We recommend that you use the new libraries for all Toradex modules. Please see the Toradex CE Libraries and Code Samples for up-to-date information.

Introduction

With the 1.3 version of the OakLib, Toradex has introduced some changes in the programming interface of the library. In most cases, migrating your application is simply a matter of recompiling and linking your application against the new version of the library, but in some cases (mainly if you are using a programming language that offers no easy bridging feature with C DLLs), you may need to tweak your code to be able to use the version 1.3 of the OakLib. This document will detail the motivation behind the changes, and tell you how to adapt your code.

Data padding

Description

In versions prior to 1.3, the OakLib used 'ALIGN' compiler directives to control the padding in data structures. In a few words, in order to optimize performance, the compiler can insert 'gaps' in data structure so that data members are optimally aligned for CPU operations. The programming languages makes sure the padding is made transparent to the user, and in most cases, you do not have to worry about padding. You can find more details about the topic in the following article. 'align' compiler directives that give control over the padding have been removed in OakLib 1.3, and data structures now use the default padding policy for the x86 platform. In practice, this means that the tChannel structure remains the same as in 1.2 and all padding bytes are removed from the tOakSensor structure (see the tables below for details).

Motivations

Align directives are not compatible with .NET.

Migration

  • C/C++, .Net langages: (re)compile your application. .Net developers may want to check our [[Oak_in_Visual_Basic_.NET_and_C_Sharp|dedicated wiki page]].
  • Other languages: if you previously had to manually specify the padding in your application, modify your code to match the structure in the following tables. Otherwise, simply recompile your application.

Memory layout of the tChannel data structure

Type Name ASCII ASCII UNICODE UNICODE
Size [bytes] Position Size [bytes] Position
bool IsSigned 1 0 1 0
BYTE BitSize 1 1 1 1
signed char UnitExponent 1 2 1 2
Padding 1 3 1 3
ULONG Unit 4 4 4 4
TCHAR UnitStr[24] 24 8 48 8
TCHAR ChannelName[24] 24 32 48 56
TCHAR UserChannelName[24] 24 56 48 104
TCHAR UserChannelName_NV[24] 24 80 48 152
BYTE RFU[64] 64 104 64 200
Total Size in Bytes 168 264

Memory layout of the tOakSensor data structure

Type Name ASCII ASCII UNICODE UNICODE
Size [bytes] Position Size [bytes] Position
TCHAR DevicePath[256] 256 0 512 0
WORD VID 2 256 2 512
WORD PID 2 258 2 514
WORD REV 2 260 2 516
TCHAR SN[24] 24 262 48 518
BYTE RFU[64] 64 286 64 566
TCHAR DeviceName[24] 24 350 48 630
TCHAR UserDeviceName[24] 24 374 48 678
TCHAR UserDeviceName_NV[24] 24 398 48 726
WORD NumChannels 2 422 2 774
tChannel Channel[MAX_NO_CHANNELS] 1848 424 2904 776
Total Size in Bytes 2272 3680

Const string parameters

Description

In version prior to 1.3, all string parameters were passed as non-const (LPTSTR). Starting with OakLib 1.3 string parameters are declared const (LPCTSTR)

Motivations

  1. The strings are not modified by the OakLib
  2. Non-const string parameters are not compatible with most C string compatibility adapter functions, like C++'s std::string::c_str()

Migration

  • C/C++: simply recompile your application
  • Other languages: if you have to provide equivalent declaration of the OakLib functions in your programming language, modify these declarations to include the constness of the string parameters.