1/*
2 * Copyright (C) 2012 Intel Corporation. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 * 1. Redistributions of source code must retain the above copyright
8 *    notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 *    notice, this list of conditions and the following disclaimer in the
11 *    documentation and/or other materials provided with the distribution.
12 *
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
14 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
17 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
23 * THE POSSIBILITY OF SUCH DAMAGE.
24 */
25
26/**
27 * @file    ewk_back_forward_list.h
28 * @brief   Describes the Ewk Back Forward List API.
29 */
30
31#ifndef ewk_back_forward_list_h
32#define ewk_back_forward_list_h
33
34#include "ewk_back_forward_list_item.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/** Creates a type name for Ewk_Back_Forward_List */
41typedef struct EwkBackForwardList Ewk_Back_Forward_List;
42
43/**
44 * Returns the current item in the @a list.
45 *
46 * @param list the back-forward list instance
47 *
48 * @return the current item in the @a list or @c NULL in case of error
49 */
50EAPI Ewk_Back_Forward_List_Item *ewk_back_forward_list_current_item_get(const Ewk_Back_Forward_List *list);
51
52/**
53 * Returns the item that precedes the current item in the @a list.
54 *
55 * @param list the back-forward list instance
56 *
57 * @return the item that precedes the current item the @a list or @c NULL in case of error
58 */
59EAPI Ewk_Back_Forward_List_Item *ewk_back_forward_list_previous_item_get(const Ewk_Back_Forward_List *list);
60
61/**
62 * Returns the item that follows the current item in the @a list.
63 *
64 * @param list the back-forward list instance
65 *
66 * @return the item that follows the current item in the @a list or @c NULL in case of error
67 */
68EAPI Ewk_Back_Forward_List_Item *ewk_back_forward_list_next_item_get(const Ewk_Back_Forward_List *list);
69
70/**
71 * Returns the item at a given @a index relative to the current item.
72 *
73 * @param list the back-forward list instance
74 * @param index the index of the item
75 *
76 * @return the item at a given @a index relative to the current item or @c NULL in case of error
77 */
78EAPI Ewk_Back_Forward_List_Item *ewk_back_forward_list_item_at_index_get(const Ewk_Back_Forward_List *list, int index);
79
80/**
81 * Returns the length of the back-forward list including current item.
82 *
83 * @param list the back-forward list instance
84 *
85 * @return the length of the back-forward list including current item or @c 0 in case of error
86 */
87EAPI unsigned ewk_back_forward_list_count(Ewk_Back_Forward_List *list);
88
89/**
90 * Creates the list containing the items preceding the current item limited by @a limit.
91 *
92 * The @c Ewk_Back_Forward_List_Item elements are located in the result list starting with the oldest one.
93 * if @a limit is equal to @c -1 all the items preceding the current item are returned.
94 *
95 * @param list the back-forward list instance
96 * @param limit the number of items to retrieve
97 *
98 * @return @c Eina_List containing @c Ewk_Back_Forward_List_Item elements or @c NULL in case of error,
99 *            the Eina_List and its items should be freed after use. Use ewk_object_unref()
100 *            to free the items
101 */
102EAPI Eina_List *ewk_back_forward_list_n_back_items_copy(const Ewk_Back_Forward_List *list, int limit);
103
104/**
105 * Creates the list containing the items following the current item limited by @a limit.
106 *
107 * The @c Ewk_Back_Forward_List_Item elements are located in the result list starting with the oldest one.
108 * if @a limit is equal to @c -1 all the items preceding the current item are returned.
109 *
110 * @param list the back-forward list instance
111 * @param limit the number of items to retrieve
112 *
113 * @return @c Eina_List containing @c Ewk_Back_Forward_List_Item elements or @c NULL in case of error,
114 *            the Eina_List and its items should be freed after use. Use ewk_object_unref()
115 *            to free the items
116 */
117EAPI Eina_List *ewk_back_forward_list_n_forward_items_copy(const Ewk_Back_Forward_List *list, int limit);
118
119/**
120 * Creates the list containing the items preceding the current item.
121 *
122 * The @c Ewk_Back_Forward_List_Item elements are located in the result list starting with the oldest one.
123 *
124 * @param list the back-forward list instance
125 *
126 * @return @c Eina_List containing @c Ewk_Back_Forward_List_Item elements or @c NULL in case of error,
127 *            the Eina_List and its items should be freed after use. Use ewk_object_unref()
128 *            to free the items
129 *
130 * @see ewk_back_forward_list_n_back_items_copy
131 */
132#define ewk_back_forward_list_back_items_copy(list) \
133    ewk_back_forward_list_n_back_items_copy(list, -1)
134
135/**
136 * Creates the list containing the items following the current item.
137 *
138 * The @c Ewk_Back_Forward_List_Item elements are located in the result list starting with the oldest one.
139 *
140 * @param list the back-forward list instance
141 *
142 * @return @c Eina_List containing @c Ewk_Back_Forward_List_Item elements or @c NULL in case of error,
143 *            the Eina_List and its items should be freed after use. Use ewk_object_unref()
144 *            to free the items
145 *
146 * @see ewk_back_forward_list_n_forward_items_copy
147 */
148#define ewk_back_forward_list_forward_items_copy(list) \
149    ewk_back_forward_list_n_forward_items_copy(list, -1)
150
151#ifdef __cplusplus
152}
153#endif
154#endif // ewk_back_forward_list_h
155