[PATCH 1/1] Add utility for services needing page_size + page_number

["Juan A. Suarez Romero" <jasuarez igalia com>]

Grilo relies in offset + count to make pagination.

But there are services like Jamendo that needs the page_number and size of
page.

For these cases, a new utility function helps user to compute page_number and
offset inside the page where she needs to start looking for data. Also it
returns an "optimal" value for page size. This optimal value is the minimum
page size needed to retrieve the data in just one query to backend.
---
 src/Makefile.am             |    5 ++-
 src/grilo.h                 |    1 +
 src/grl-util.c              |   85 +++++++++++++++++++++++++++++++++++++++++++
 src/{grilo.h => grl-util.h} |   43 ++++++----------------
 4 files changed, 101 insertions(+), 33 deletions(-)
 create mode 100644 src/grl-util.c
 copy src/{grilo.h => grl-util.h} (56%)

diff --git a/src/Makefile.am b/src/Makefile.am
index 7a7564a..67bc2d8 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -23,7 +23,7 @@ lib GRL_NAME@_la_SOURCES =					\
 	grl-plugin-registry.c					\
 	grl-metadata-key.c grl-metadata-key-priv.h		\
 	grl-metadata-source.c grl-metadata-source-priv.h	\
-	grl-media-source.c					\
+	grl-media-source.c grl-util.c				\
 	grl-multiple.c						\
 	grl-log.c						\
 	grilo.c
@@ -51,7 +51,8 @@ lib GRL_NAME@inc_HEADERS =	\
 	grl-metadata-source.h	\
 	grl-media-source.h	\
 	grl-log.h 		\
-	grl-multiple.h
+	grl-multiple.h		\
+	grl-util.h
 
 data_h_headers =		\
 	data/grl-data.h		\
diff --git a/src/grilo.h b/src/grilo.h
index 5991197..552310f 100644
--- a/src/grilo.h
+++ b/src/grilo.h
@@ -48,6 +48,7 @@
 #include <grl-media-box.h>
 #include <grl-config.h>
 #include <grl-multiple.h>
+#include <grl-util.h>
 
 #undef _GRILO_H_INSIDE_
 
diff --git a/src/grl-util.c b/src/grl-util.c
new file mode 100644
index 0000000..7807813
--- /dev/null
+++ b/src/grl-util.c
@@ -0,0 +1,85 @@
+/*
+ * Copyright (C) 2010 Igalia S.L.
+ *
+ * Contact: Iago Toral Quiroga <itoral igalia com>
+ *
+ * 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; version 2.1 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., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA
+ *
+ */
+
+#include "grl-util.h"
+
+/**
+ * grl_paging_translate:
+ * @skip: number of elements to skip
+ * @count: number of elements to retrieve
+ * @max_page_size: maximum value for page size
+ * @page_size: optimal page size
+ * @page_number: page which contain the first element to retrieve (starting at 1)
+ * @internal_offset: in the @page_number, offset where first element can be found (starting at 0)
+ *
+ * Grilo browsing implements a paging mechanism through @skip and @count values.
+ *
+ * But there are some services (like Jamendo or Flickr) where paging is done
+ * through a page number and page size: user request all elements in a page,
+ * specifying in most cases what is the page size.
+ *
+ * This function is a helper for this task, computing from @skip and @count what
+ * is the optimal value of page size (limited by @max_page_size), which page
+ * should the user request, and where requested data start inside the page.
+ *
+ * By optimal we mean that it computes those values so only one page is required
+ * to satisfy the data, using the smallest page size. If user is limiting page
+ * size, then more requests to services might be needed. But still page size
+ * will be an optimal value.
+ **/
+void grl_paging_translate (guint skip,
+                           guint count,
+                           guint max_page_size,
+                           guint *page_size,
+                           guint *page_number,
+                           guint *internal_offset)
+{
+  gulong _page_size;
+  gulong last_element;
+
+  if (skip < count) {
+    _page_size = skip + count;
+    if (max_page_size > 0) {
+      _page_size = CLAMP (_page_size, 0, max_page_size);
+    }
+  } else {
+    _page_size = count;
+    last_element = skip + count - 1;
+    while (skip/_page_size != last_element/_page_size &&
+           (max_page_size == 0 || _page_size < max_page_size)) {
+      _page_size++;
+    }
+  }
+  _page_size = CLAMP (_page_size, 0, G_MAXUINT);
+
+  if (page_size) {
+    *page_size = _page_size;
+  }
+
+  if (page_number) {
+    *page_number = skip/_page_size + 1;
+  }
+
+  if (internal_offset) {
+    *internal_offset = skip%_page_size;
+  }
+}
diff --git a/src/grilo.h b/src/grl-util.h
similarity index 56%
copy from src/grilo.h
copy to src/grl-util.h
index 5991197..a3f81ee 100644
--- a/src/grilo.h
+++ b/src/grl-util.h
@@ -20,43 +20,24 @@
  *
  */
 
-#ifndef _GRILO_H_
-#define _GRILO_H_
-
-#define _GRILO_H_INSIDE_
-
-#ifdef HAVE_CONFIG_H
-# ifndef PACKAGE
-#  include "config.h"
-# endif
+#if !defined (_GRILO_H_INSIDE_) && !defined (GRILO_COMPILATION)
+#error "Only <grilo.h> can be included directly."
 #endif
 
-#include <glib.h>
-
-#include <grl-error.h>
-#include <grl-log.h>
-#include <grl-plugin-registry.h>
-#include <grl-media-plugin.h>
-#include <grl-media-source.h>
-#include <grl-metadata-source.h>
-#include <grl-metadata-key.h>
-#include <grl-data.h>
-#include <grl-media.h>
-#include <grl-media-audio.h>
-#include <grl-media-video.h>
-#include <grl-media-image.h>
-#include <grl-media-box.h>
-#include <grl-config.h>
-#include <grl-multiple.h>
+#ifndef _GRL_UTIL_H_
+#define _GRL_UTIL_H_
 
-#undef _GRILO_H_INSIDE_
+#include <glib.h>
 
 G_BEGIN_DECLS
 
-void grl_init (gint *argc, gchar **argv[]);
-
-GOptionGroup *grl_init_get_option_group (void);
+void grl_paging_translate (guint skip,
+                           guint count,
+                           guint max_page_size,
+                           guint *page_size,
+                           guint *page_number,
+                           guint *internal_offset);
 
 G_END_DECLS
 
-#endif /* _GRILO_H_ */
+#endif /* _GRL_UTIL_H_ */
-- 
1.7.0.4