1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 2015, Digium, Inc.
*
* Matt Jordan <mjordan@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
/*!
* \file
* \brief An in-memory media cache
*/
#ifndef _ASTERISK_MEDIA_CACHE_H
#define _ASTERISK_MEDIA_CACHE_H
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
struct ast_variable;
/*!
* \brief Check if an item exists in the cache
*
* \param uri The unique URI for the media item
*
* \retval 0 uri does not exist in cache
* \retval 1 uri does exist in cache
*/
int ast_media_cache_exists(const char *uri);
/*!
* \brief Retrieve an item from the cache
*
* \param uri The unique URI for the media item
* \param preferred_file_name The preferred name for the file storing the
* media once it is retrieved. Can be NULL.
* \param file_path Buffer to store the full path to the media in the
* cache
* \param len The length of the buffer pointed to by \c file_path
*
* \retval 0 The item was retrieved successfully
* \retval -1 The item could not be retrieved
*
* Example Usage:
* \code
* char media[PATH_MAX];
* int res;
*
* res = ast_media_cache_retrieve("http://localhost/foo.wav", NULL,
* media, sizeof(media));
* \endcode
*
* \details
* Retrieving an item will cause the \ref bucket Bucket backend associated
* with the URI scheme in \c uri to be queried. If the Bucket backend
* does not require an update, the cached information is used to find the
* file associated with \c uri, and \c file_path is populated with the
* location of the media file associated with \c uri.
*
* If the item is not in the cache, the item will be retrieved using the
* \ref bucket backend. When this occurs, if \c preferred_file_name is given,
* it will be used as the destination file for the retrieval. When retrieval
* of the media from the backend is complete, \c file_path is then populated
* as before.
*/
int ast_media_cache_retrieve(const char *uri, const char *preferred_file_name,
char *file_path, size_t len);
/*!
* \brief Retrieve metadata from an item in the cache
*
* \param uri The unique URI for the media item
* \param key The key of the metadata to retrieve
* \param value Buffer to store the value in
* \param len The length of the buffer pointed to by \c value
*
* \retval 0 The metadata was retrieved successfully
* \retval -1 The metadata could not be retrieved
*
* Example Usage:
* \code
*
* int res;
* char file_size[32];
*
* res = ast_media_cache_retrieve_metadata("http://localhost/foo.wav", "size",
* file_size, sizeof(file_size));
* \endcode
*/
int ast_media_cache_retrieve_metadata(const char *uri, const char *key,
char *value, size_t len);
/*!
* \brief Create/update a cached media item
*
* \param uri The unique URI for the media item to store in the cache
* \param file_path Full path to the media file to be cached
* \param metadata Metadata to store with the cached item
*
* \retval 0 The item was cached
* \retval -1 An error occurred when creating/updating the item
*
* Example Usage:
* \code
* int res;
*
* res = ast_media_cache_create_or_update("http://localhost/foo.wav",
* "/tmp/foo.wav", NULL);
* \endcode
*
* \note This method will overwrite whatever has been provided by the
* \ref bucket backend.
*
* \details
* While \ref ast_media_cache_retrieve is used to retrieve media from
* some \ref bucket provider, this method allows for overwriting what
* is provided by a backend with some local media. This is useful for
* reconstructing or otherwise associating local media with a remote
* URI, deferring updating of the media from the backend to some later
* retrieval.
*/
int ast_media_cache_create_or_update(const char *uri, const char *file_path,
struct ast_variable *metadata);
/*!
* \brief Remove an item from the media cache
*
* \param uri The unique URI for the media item to store in the cache
*
* \retval 0 success
* \retval -1 error
*
* Example Usage:
* \code
* int res;
*
* res = ast_media_cache_delete("http://localhost/foo.wav");
* \endcode
*
* \details
* This removes an item completely from the media cache. Any files local
* on disk associated with the item are deleted as well.
*
* \note It is up to the \ref bucket implementation whether or not this
* affects any non-local storage
*/
int ast_media_cache_delete(const char *uri);
/*!
* \brief Initialize the media cache
*
* \note This should only be called once, during Asterisk initialization
*
* \retval 0 success
* \retval -1 error
*/
int ast_media_cache_init(void);
#if defined(__cplusplus) || defined(c_plusplus)
}
#endif
#endif /* _ASTERISK_MEDIA_CACHE_H */
|
