libgphoto2 photo camera library (libgphoto2) API: gphoto2/gphoto2-list.h File Reference

libgphoto2 photo camera library (libgphoto2) API 2.5.2

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

Typedefs | Functions
gphoto2-list.h File Reference

Go to the source code of this file.

## Typedefs
typedef struct _CameraList | CameraList
| A generic list. More...

## Functions
int | gp_list_new (CameraList **list)
| Creates a new CameraList. More...
int | gp_list_ref (CameraList *list)
| Increments the reference count of the list. More...
int | gp_list_unref (CameraList *list)
| Decrements the reference count of the `list`. More...
int | gp_list_free (CameraList *list)
int | gp_list_count (CameraList *list)
int | gp_list_append (CameraList *list, const char *name, const char *value)
int | gp_list_reset (CameraList *list)
int | gp_list_sort (CameraList *list)
int | gp_list_find_by_name (CameraList *list, int *index, const char *name)
int | gp_list_get_name (CameraList *list, int index, const char **name)
int | gp_list_get_value (CameraList *list, int index, const char **value)
int | gp_list_set_name (CameraList *list, int index, const char *name)
int | gp_list_set_value (CameraList *list, int index, const char *value)
int | gp_list_populate (CameraList *list, const char *format, int count)

## Detailed Description

Lists of files, folders, cameras, etc.

Author
  Copyright 2001 Scott Fritzinger

Note
  This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
  This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
  You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

## Typedef Documentation

typedef struct _CameraList CameraList

A generic list.

This structure provides a list with name:value pairs that is used in various parts of libgphoto2. Its details are internal, please use the gp_list_xxx accessor functions.

Usage pattern for CameraList for users external of libgphoto2, such as libgphoto2 frontends:

CameraList *list;
gp_list_new (&list);
init_list_somehow (list);
for (i=0; i < gp_list_count(list); i++) {
char *name, *value;
gp_list_get_name (list, i, &name);
gp_list_get_name (list, i, &value);
do_something_with (name, value);
}
gp_list_free (list);

Please do NOT directly instantiate a CameraList object like this:

CameraList foo; // DO NOT DO THIS

Please do NOT directly access the structure members like this:

list->entry[i].name // DO NOT DO THIS

## Function Documentation

int gp_list_append | ( | CameraList * | list,
|  | const char * | name,
|  | const char * | value
| ) |  |

Appends `name` and `value` to the `list`.

Parameters

  list | a CameraList
  name | the name of the entry to append
  value | the value of the entry to append

Returns
  a gphoto2 error code

References CHECK_LIST, GP_ERROR_NO_MEMORY, and GP_OK.

Referenced by gp_abilities_list_detect(), gp_camera_autodetect(), gp_filesystem_list_files(), gp_filesystem_list_folders(), and gp_list_populate().

int gp_list_count | ( | CameraList * | list | ) |

Counts the entries in the `list`.

Parameters

  list | a CameraList

Returns
  a gphoto2 error code

References CHECK_LIST.

Referenced by gp_camera_autodetect(), gp_camera_init(), gp_filesystem_list_files(), and gp_filesystem_list_folders().

int gp_list_find_by_name | ( | CameraList * | list,
|  | int * | index,
|  | const char * | name
| ) |  |

Retrieves the `index` of an arbitrary entry with `name`.

Parameters

  list | a CameraList
  index | pointer to the result index (may be NULL, only set if found)
  name | name of the entry

Returns
  a gphoto2 error code: GP_OK if found.

No guarantees as to the speed of the search, or in what sequence the list is searched.

References CHECK_LIST, GP_ERROR, and GP_OK.

int gp_list_free | ( | CameraList * | list | ) |

Frees the `list`. It is recommended to use gp_list_unref instead.

Parameters

  list | the CameraList to be freed

Returns
  a gphoto2 error code

References CHECK_LIST, and GP_OK.

Referenced by gp_camera_autodetect(), gp_camera_init(), gp_filesystem_number(), gp_filesystem_remove_dir(), and gp_list_unref().

int gp_list_get_name | ( | CameraList * | list,
|  | int | index,
|  | const char ** | name
| ) |  |

Retrieves the `name` of entry with `index`.

Parameters

  list | a CameraList
  index | index of the entry
  name |

Returns
  a gphoto2 error code.

References CHECK_LIST, and GP_OK.

Referenced by gp_camera_autodetect(), gp_camera_init(), gp_filesystem_list_files(), and gp_filesystem_list_folders().

int gp_list_get_value | ( | CameraList * | list,
|  | int | index,
|  | const char ** | value
| ) |  |

Retrieves the value of entry with `index`.

Parameters

  list | a CameraList
  index | index of the entry
  value |

Returns
  a gphoto2 error code

References CHECK_LIST, and GP_OK.

Referenced by gp_camera_autodetect(), and gp_camera_init().

int gp_list_new | ( | CameraList ** | list | ) |

Creates a new CameraList.

Parameters

  list |

Returns
  a gphoto2 error code

References GP_ERROR_NO_MEMORY, and GP_OK.

Referenced by gp_camera_autodetect(), gp_camera_init(), gp_filesystem_number(), and gp_filesystem_remove_dir().

int gp_list_populate | ( | CameraList * | list,
|  | const char * | format,
|  | int | count
| ) |  |

Adds `count` entries to the list.

Parameters

  list | a CameraList
  format | the format
  count | number of entries to be added to the list return a gphoto2 error code

Typically, this function is called by a camera driver when there is no way of retrieving the real name of a picture. In this case, when asked for a file list (see #CameraFilesystemListFunc), the list is populated with dummy names generated by this function.

References CHECK_LIST, gp_list_append(), gp_list_reset(), and GP_OK.

int gp_list_ref | ( | CameraList * | list | ) |

Increments the reference count of the list.

Parameters

  list | a CameraList

Returns
  a gphoto2 error code.

References CHECK_LIST, and GP_OK.

int gp_list_reset | ( | CameraList * | list | ) |

Resets the `list` and removes all entries.

Parameters

  list | a CameraList

Returns
  a gphoto2 error code

References CHECK_LIST, and GP_OK.

Referenced by gp_abilities_list_detect(), gp_camera_folder_list_files(), gp_camera_folder_list_folders(), gp_filesystem_list_files(), gp_filesystem_list_folders(), and gp_list_populate().

int gp_list_set_name | ( | CameraList * | list,
|  | int | index,
|  | const char * | name
| ) |  |

Sets the name of an entry.

Parameters

  list | a CameraList
  index | index of entry
  name | name to be set

Returns
  a gphoto2 error code

References CHECK_LIST, GP_ERROR_NO_MEMORY, and GP_OK.

int gp_list_set_value | ( | CameraList * | list,
|  | int | index,
|  | const char * | value
| ) |  |

Sets the `value` of an entry.

Parameters

  list | a CameraList
  index | index of the entry
  value | the value to be set

Returns
  a gphoto2 error code

References CHECK_LIST, GP_ERROR_NO_MEMORY, and GP_OK.

int gp_list_sort | ( | CameraList * | list | ) |

Sorts the `list` entries with respect to the names.

Parameters

  list | a CameraList

Returns
  a gphoto2 error code

References CHECK_LIST, and GP_OK.

Referenced by gp_camera_folder_list_files(), and gp_camera_folder_list_folders().

int gp_list_unref | ( | CameraList * | list | ) |

Decrements the reference count of the `list`.

Parameters

  list | a CameraList

Returns
  a gphoto2 error code

If there are no references left, the `list` will be freed.

References CHECK_LIST, gp_list_free(), and GP_OK.