lensfun: lfDatabase Struct Reference

lensfun 0.3.95.0

Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
lfDatabase Struct Reference
Database functions

A lens database object. More...

`#include <lensfun.h>`

## Public Member Functions
| lfDatabase ()
| Database object constructor.
| ~lfDatabase ()
| Database object destructor.
DEPRECATED void | Destroy ()
| Destroy the database object and free all loaded data. More...
DEPRECATED bool | LoadDirectory (const char *dirname)
| Open and parse all XML files in a given directory. More...
lfError | Load ()
| Find and load the lens database. More...
lfError | Load (const char *pathname)
| Load the database from specific path (directory or file). More...
lfError | Load (const char *data, size_t data_size)
| Load a database from memory. More...
lfError | Save (const char *filename) const
| Save the whole database to a file. More...
char * | Save () const
| Save the database into a memory array. More...
const lfCamera ** | FindCameras (const char *maker, const char *model) const
| Find a set of cameras that fit given criteria. More...
const lfCamera ** | FindCamerasExt (const char *maker, const char *model, int sflags=0) const
| Searches all translations of camera maker and model. More...
const lfCamera *const * | GetCameras ()
| Retrieve a full list of cameras. More...
const lfLens ** | FindLenses (const lfCamera *camera, const char *maker, const char *model, int sflags=0) const
| Parse a human-friendly lens description (ex: "smc PENTAX-F 35-105mm F4-5.6" or "SIGMA AF 28-300 F3.5-5.6 DL IF") and return a list of lfLens'es which are matching this description. More...
const lfLens *const * | GetLenses ()
| Retrieve a full list of lenses. More...
const lfMount * | FindMount (const char *mount) const
| Return the lfMount structure given the (basic) mount name. More...
const char * | MountName (const char *mount) const
| Get the name of a mount in current locale. More...
const lfMount *const * | GetMounts ()
| Retrieve a full list of mounts. More...
void | AddMount (lfMount *mount)
| Add a mount to the database. More...
void | AddCamera (lfCamera *camera)
| Add a camera to the database. More...
void | AddLens (lfLens *lens)
| Add a lens to the database. More...

## Static Public Member Functions
static DEPRECATED lfDatabase * | Create ()
| Create a new empty database object. More...
static long int | ReadTimestamp (const char *dirname)
| Scans for the timestamp of a Lensfun database. More...

## Public Attributes
DEPRECATED char * | HomeDataDir
| Home lens database directory (deprecated). Replaced by lfDatabase::UserLocation.
DEPRECATED char * | UserUpdatesDir
| Home lens database directory for automatic updates (deprecated). Replaced by lfDatabase::UserUpdatesLocation.

## Static Public Attributes
static const char *const | UserLocation
| Home lens database directory (something like "~/.local/share/lensfun")
static const char *const | UserUpdatesLocation
| Home lens database directory for automatic updates (something like "~/.local/share/lensfun/updates")
static const char *const | SystemLocation
| System lens database directory (something like "/usr/share/lensfun")
static const char *const | SystemUpdatesLocation
| System lens database directory for automatic updates (something like "/var/lib/lensfun-updates")

## Detailed Description

A lens database object.

This object contains a list of mounts, cameras and lenses through which you can search. The objects are loaded from XML files (see How database files are found and loaded).

Objects loaded later override objects loaded earlier. Thus, if user modifies a object you must save it to its home directory (see lfDatabase::UserLocation), where it will override any definitions from the system-wide database.

Examples
  example.c, lenstool.cpp, and tfun.cpp.

## Member Function Documentation

## ◆ AddCamera()

void lfDatabase::AddCamera | ( | lfCamera * | camera | ) |

Add a camera to the database.

Ownership will be transferred to the lfDatabase class and the respective object will be deleted when the database object is deleted.

Parameters

  camera | the camera to add

## ◆ AddLens()

void lfDatabase::AddLens | ( | lfLens * | lens | ) |

Add a lens to the database.

Ownership will be transferred to the lfDatabase class and the respective object will be deleted when the database object is deleted.

Parameters

  lens | the lens to add

## ◆ AddMount()

void lfDatabase::AddMount | ( | lfMount * | mount | ) |

Add a mount to the database.

Ownership will be transferred to the lfDatabase class and the respective object will be deleted when the database object is deleted.

Parameters

  mount | the mount to add

## ◆ Create()

static DEPRECATED lfDatabase * lfDatabase::Create | ( |  | ) |
| static

Create a new empty database object.

This function is deprecated and will be removed in the future. Please use the standard constructor instead.

## ◆ Destroy()

DEPRECATED void lfDatabase::Destroy | ( |  | ) |

Destroy the database object and free all loaded data.

This function is deprecated and will be removed in the future. Please use the standard destructor instead.

Examples
  tfun.cpp.

## ◆ FindCameras()

const lfCamera ** lfDatabase::FindCameras | ( | const char * | maker,
|  | const char * | model
| ) |  | const

Find a set of cameras that fit given criteria.

The maker and model must be given (if possible) exactly as they are spelled in database, except that the library will compare case-insensitively and will compress spaces. This means that the database must contain camera maker/lens exactly how it is given in EXIF data, but you may add human-friendly translations of them using the multi-language string feature (including a translation to "en" to avoid displaying EXIF tags in user interface - they are often upper-case which looks ugly).

Parameters

  maker | Camera maker (either from EXIF tags or from some other source). The string is expected to be pure ASCII, since EXIF data does not allow 8-bit data to be used.
  model | Camera model (either from EXIF tags or from some other source). The string is expected to be pure ASCII, since EXIF data does not allow 8-bit data to be used.

Returns
  A NULL-terminated list of cameras matching the search criteria or NULL if none. Release return value with lf_free() (only the list of pointers, not the camera objects!).

## ◆ FindCamerasExt()

const lfCamera ** lfDatabase::FindCamerasExt | ( | const char * | maker,
|  | const char * | model,
|  | int | sflags = `0`
| ) |  | const

Searches all translations of camera maker and model.

Thus, you may search for a user-entered camera even in a language different from English. This function is somewhat similar to FindCameras(), but uses a different search algorithm.

This is a lot slower than FindCameras().

Parameters

  maker | Camera maker. This can be any UTF-8 string.
  model | Camera model. This can be any UTF-8 string.
  sflags | Additional flags influencing the search algorithm. This is a combination of LF_SEARCH_XXX flags.

Returns
  A NULL-terminated list of cameras matching the search criteria or NULL if none. Release return value with lf_free() (only the list of pointers, not the camera objects!).

Examples
  lenstool.cpp.

## ◆ FindLenses()

const lfLens ** lfDatabase::FindLenses | ( | const lfCamera * | camera,
|  | const char * | maker,
|  | const char * | model,
|  | int | sflags = `0`
| ) |  | const

Parse a human-friendly lens description (ex: "smc PENTAX-F 35-105mm F4-5.6" or "SIGMA AF 28-300 F3.5-5.6 DL IF") and return a list of lfLens'es which are matching this description.

Multiple lenses may be returned if multiple lenses match (perhaps due to non-unique lens description provided, e.g. "Pentax SMC").

The matching algorithm works as follows: first the user description is tried to be interpreted according to several well-known lens naming schemes, so additional data like focal and aperture ranges are extracted if they are present. After that word matching is done; a lens matches the description ONLY IF it contains all the words found in the description (including buzzwords e.g. IF IZ AL LD DI USM SDM etc). Order of the words does not matter. An additional check is done on the focal/aperture ranges, they must exactly match if they are specified.

Parameters

  camera | The camera (can be NULL if camera is unknown, or just certain fields in structure can be NULL). The algorithm will look for a lens with crop factor not larger than of given camera, since the mathematical models of the lens can be incorrect for sensor sizes larger than the one used for calibration. Also camera mount is taken into account, the lenses with incompatible mounts will be filtered out.
  maker | Lens maker or NULL if not known.
  model | A human description of the lens model(-s).
  sflags | Additional flags influencing the search algorithm. This is a combination of LF_SEARCH_XXX flags.

Returns
  A list of lenses parsed from user description or NULL. Release memory with lf_free(). The list is ordered in the most-likely to least-likely order, e.g. the first returned value is the most likely match.

Examples
  lenstool.cpp, and tfun.cpp.

## ◆ FindMount()

const lfMount * lfDatabase::FindMount | ( | const char * | mount | ) | const

Return the lfMount structure given the (basic) mount name.

Parameters

  mount | The basic mount name.

Returns
  A pointer to lfMount structure or NULL.

## ◆ GetCameras()

const lfCamera *const * lfDatabase::GetCameras | ( |  | ) |

Retrieve a full list of cameras.

Returns
  An NULL-terminated list containing all cameras loaded until now. The list is valid only until the lens database is modified. The returned pointer does not have to be freed.

## ◆ GetLenses()

const lfLens *const * lfDatabase::GetLenses | ( |  | ) |

Retrieve a full list of lenses.

Returns
  An NULL-terminated list containing all lenses loaded until now. The list is valid only until the lens database is modified. The returned pointer does not have to be freed.

## ◆ GetMounts()

const lfMount *const * lfDatabase::GetMounts | ( |  | ) |

Retrieve a full list of mounts.

Returns
  An array containing all mounts loaded until now. The list is valid only until the mount database is modified. The returned pointer does not have to be freed.

## ◆ Load() [1/3]

lfError lfDatabase::Load | ( |  | ) |

Find and load the lens database.

This function automatically tries to determine the location of the lens database on the system. See How database files are found and loaded for more information.

Returns
  LF_NO_ERROR or a error code.

Examples
  lenstool.cpp, and tfun.cpp.

## ◆ Load() [2/3]

lfError lfDatabase::Load | ( | const char * | data,
|  | size_t | data_size
| ) |  |

Load a database from memory.

Parameters

  data | The XML data.
  data_size | Data size in bytes.

Returns
  LF_NO_ERROR or a error code.

## ◆ Load() [3/3]

lfError lfDatabase::Load | ( | const char * | pathname | ) |

Load the database from specific path (directory or file).

If the given path is a folder, all included XML files will be parsed for valid lens data. If a loaded file contains the specification of a camera/lens that's already in memory, it overrides that data.

Parameters

  pathname | The name of a XML file to load. Note that Lensfun does not support the full XML specification as it uses the glib's simple XML parser, so advanced XML features are not available.

Returns
  LF_NO_ERROR or a error code.

## ◆ LoadDirectory()

DEPRECATED bool lfDatabase::LoadDirectory | ( | const char * | dirname | ) |

Open and parse all XML files in a given directory.

Returns true if valid Lensfun XML data was found and loaded sucessfully.

This function is deprecated and will be removed in the future. Please use the lfDatabase::Load(const char *pathname) syntax instead.

Parameters

  dirname | The directory to be read.

Returns
  True if valid lensfun XML data was succesfully loaded.

## ◆ MountName()

const char * lfDatabase::MountName | ( | const char * | mount | ) | const

Get the name of a mount in current locale.

Parameters

  mount | The basic mount name.

Returns
  The name of the mount in current locale (UTF-8 string).

## ◆ ReadTimestamp()

static long int lfDatabase::ReadTimestamp | ( | const char * | dirname | ) |
| static

Scans for the timestamp of a Lensfun database.

"database" means here a directory containing XML files. If it also contains a file timestamp.txt, its content is interpreted as a string-encoded floating point value, representing the timestamp in seconds since the Epoch (UNIX time). If it is not present, 0 is returned. If the directory is not found or empty, a negative value is returned.

Parameters

  dirname | the name of the directory containing a Lensfun database

Returns
  the UNIX timestamp when database was last updated.

## ◆ Save() [1/2]

char * lfDatabase::Save | ( |  | ) | const

Save the database into a memory array.

Returns
  A pointer to an allocated string with the XML data. Free it with lf_free().

## ◆ Save() [2/2]

lfError lfDatabase::Save | ( | const char * | filename | ) | const

Save the whole database to a file.

Parameters

  filename | The file name to write the XML stream into.

Returns
  LF_NO_ERROR or a error code.

The documentation for this struct was generated from the following file:

- lensfun.h