gphoto2-list.c File Reference

#include "config.h"
#include <gphoto2/gphoto2-list.h>
#include <gphoto2/gphoto2-port-log.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <gphoto2/gphoto2-result.h>

Include dependency graph for gphoto2-list.c:

Defines
#define	CHECK_NULL(r)   {if (!(r)) return (GP_ERROR_BAD_PARAMETERS);}
#define	CHECK_RESULT(result)   {int r = (result); if (r < 0) return (r);}
#define	CHECK_LIST(list)
#define	CAMERALIST_STRUCT_COMPATIBILITY
#define	MAX_ENTRIES   1024
#define	MAX_LIST_STRING_LENGTH   128
#define	CHECK_INDEX_RANGE(list, index)
Functions
int	gp_list_new (CameraList **list)
	Creates a new CameraList.
int	gp_list_ref (CameraList *list)
	Increments the reference count of the list.
int	gp_list_unref (CameraList *list)
	Decrements the reference count of the list.
int	gp_list_free (CameraList *list)
int	gp_list_reset (CameraList *list)
int	gp_list_append (CameraList *list, const char *name, const char *value)
int	gp_list_sort (CameraList *list)
int	gp_list_count (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_value (CameraList *list, int index, const char *value)
int	gp_list_set_name (CameraList *list, int index, const char *name)
int	gp_list_populate (CameraList *list, const char *format, int count)

---

Detailed Description

Author:

Copyright 2000 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.

---

Define Documentation

#define CAMERALIST_STRUCT_COMPATIBILITY

Whether to preserve binary compatibility for structure internals.

Question: Find out whether any libgphoto2 frontend relies on those internals. Answer: They do, at least by instantiation a "struct CameraList foo;".

Binary compatibility and problems: * fixed string size for name and value * fixed max number of entries * some apps instantiate a "struct CameraList foo;" directly and thus reserve a specific amount of memory * FIXME: Do frontends rely on the memory layout and size of their "struct CameraList" or "struct CameraList *" when accessing its members? They *SHOULD* use access functions.

#define CHECK_INDEX_RANGE	(	list,
		index		)

Value:

do {                                                    \
    if (index < 0 || index >= list->count) {            \
      return (GP_ERROR_BAD_PARAMETERS);                 \
    }                                                   \
  } while (0)

#define CHECK_LIST

(

list

)

Value:

do {                                                    \
    if (NULL == list) {                                 \
      return (GP_ERROR_BAD_PARAMETERS);                 \
    } else if (list->ref_count == 0) {                  \
      /* catch calls to already freed list */           \
      return (GP_ERROR_BAD_PARAMETERS);                 \
    }                                                   \
  } while (0)

check that the list is valid

#define MAX_ENTRIES   1024

Internal _CameraList data structure

---

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

int gp_list_count

(

CameraList *

list

)

Counts the entries in the list.

Parameters:

list

a CameraList

Returns:

a gphoto2 error code

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.

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

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.

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

int gp_list_new

(

CameraList **

list

)

Creates a new CameraList.

Parameters:

list

Returns:

a gphoto2 error code

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.

int gp_list_ref

(

CameraList *

list

)

Increments the reference count of the list.

Parameters:

list

a CameraList

Returns:

a gphoto2 error code.

int gp_list_reset

(

CameraList *

list

)

Resets the list and removes all entries.

Parameters:

list

a CameraList

Returns:

a gphoto2 error code

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

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

int gp_list_sort

(

CameraList *

list

)

Sorts the list entries with respect to the names.

Parameters:

list

a CameraList

Returns:

a gphoto2 error code

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.

---