Yoctopuce Yocto-RangeFinder, Руководство пользователя

Страница: 68 / 497

yFreeAPI () ;
return 0 ;
}
10.3. Error handling
When you implement a program which must interact with USB modules, you cannot disregard error
handling. Inevitably, there will be a time when a user will have unplugged the device, either before
running the software, or even while the software is running. The Yoctopuce library is designed to help
you support this kind of behavior, but your code must nevertheless be conceived to interpret in the
best possible way the errors indicated by the library.
The simplest way to work around the problem is the one used in the short examples provided in this
chapter: before accessing a module, check that it is online with the
isOnline
function, and then
hope that it will stay so during the fraction of a second necessary for the following code lines to run.
This method is not perfect, but it can be sufficient in some cases. You must however be aware that
you cannot completely exclude an error which would occur after the call to
isOnline
and which
could crash the software. The only way to prevent this is to implement one of the two error handling
techniques described below.
The method recommended by most programming languages for unpredictable error handling is the
use of exceptions. By default, it is the behavior of the Yoctopuce library. If an error happens while
you try to access a module, the library throws an exception. In this case, there are three possibilities:
• If your code catches the exception and handles it, everything goes well.
• If your program is running in debug mode, you can relatively easily determine where the
problem happened and view the explanatory message linked to the exception.
• Otherwise... the exception makes your program crash, bang!
As this latest situation is not the most desirable, the Yoctopuce library offers another possibility for
error handling, allowing you to create a robust program without needing to catch exceptions at every
line of code. You simply need to call the
YAPI.DisableExceptions()
function to commute the
library to a mode where exceptions for all the functions are systematically replaced by specific return
values, which can be tested by the caller when necessary. For each function, the name of each
return value in case of error is systematically documented in the library reference. The name always
follows the same logic: a
get_state()
method returns a
Y_STATE_INVALID
value, a
get_currentValue
method returns a
Y_CURRENTVALUE_INVALID
value, and so on. In any
case, the returned value is of the expected type and is not a null pointer which would risk crashing
your program. At worst, if you display the value without testing it, it will be outside the expected
bounds for the returned value. In the case of functions which do not normally return information, the
return value is
YAPI_SUCCESS
if everything went well, and a different error code in case of failure.
When you work without exceptions, you can obtain an error code and an error message explaining
the source of the error. You can request them from the object which returned the error, calling the
errType()
and
errMessage()
methods. Their returned values contain the same information as
in the exceptions when they are active.
10.4. Integration variants for the C++ Yoctopuce library
Depending on your needs and on your preferences, you can integrate the library into your projects in
several distinct manners. This section explains how to implement the different options.
Integration in source format
Integrating all the sources of the library into your projects has several advantages:
• It guaranties the respect of the compilation conventions of your project (32/64 bits, inclusion of
debugging symbols, unicode or ASCII characters, etc.);
10. Using Yocto-RangeFinder with C++
62 www.yoctopuce.com