summaryrefslogtreecommitdiffstats
path: root/libparc/parc/algol/parc_File.h
blob: 42ef232ea776fe3a09cd55bb5fa62a697a99e561 (plain)
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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
/*
 * Copyright (c) 2017 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file parc_File.h
 * @ingroup inputoutput
 * @brief File manipulation
 *
 *
 */
#ifndef libparc_parc_File_h
#define libparc_parc_File_h

#include <stdbool.h>

#include <parc/algol/parc_BufferComposer.h>

#ifdef PARCLibrary_DISABLE_VALIDATION
#  define parcFile_OptionalAssertValid(_instance_)
#else
#  define parcFile_OptionalAssertValid(_instance_) parcFile_AssertValid(_instance_)
#endif

struct parc_file;
typedef struct parc_file PARCFile;

/**
 * Creates a `PARCFile` object named by pathname.
 *
 * This operation does not imply any I/O operations.
 * The PARCFile instance only represents the pathname,
 * and does not necessarily reference a real file.
 *
 * @param [in] pathname is a pointer to a char array (string)
 * @return A pointer to an instance of `PARCFile`
 *
 * Example:
 * @code
 * <#example#>
 * @endcode
 */
PARCFile *parcFile_Create(const char *pathname);

/**
 * Acquire a new reference to an instance of `PARCFile`.
 *
 * The reference count to the instance is incremented.
 *
 * @param [in] file The instance of `PARCFile` to which to refer.
 *
 * @return The same value as the input parameter @p file
 *
 * Example:
 * @code
 * {
 *     <#example#>
 * }
 * @endcode
 */
PARCFile *parcFile_Acquire(const PARCFile *file);

/**
 * Assert that an instance of `PARCFile` is valid.
 *
 * Valid means the internal state of the type is consistent with its required current or future behaviour.
 * This may include the validation of internal instances of types.
 *
 * @param [in] instance A pointer to a `PARCFile` instance.
 *
 * Example:
 * @code
 * {
 *     PARCFile *file = parcFile_Create("/tmp/foo");
 *
 *     parcFile_AssertValid(file);
 * }
 * @endcode
 */
void parcFile_AssertValid(const PARCFile *instance);

/**
 * Release a `PARCFile` reference.
 *
 * Only the last invocation where the reference count is decremented to zero,
 * will actually destroy the `PARCFile`.
 *
 * @param [in,out] filePtr is a pointer to the `PARCFile` reference.
 *
 * Example:
 * @code
 * <#example#>
 * @endcode
 */
void parcFile_Release(PARCFile **filePtr);

/**
 * Create a new file on storage.
 *
 * @param [in] file A pointer to an instance of `PARCFile`
 *
 * @return true if succesful, false if not
 *
 * Example:
 * @code
 * {
 *     <#example#>
 * }
 * @endcode
 */
bool parcFile_CreateNewFile(const PARCFile *file);

/**
 * Return true if the PARCFile exists on storage.
 *
 * If the pathname can be stat(2)'d, then it exists.
 *
 * @param [in] file A pointer to a `PARCFile` instance.
 * @return true if the file exists, false otherwise
 *
 * Example:
 * @code
 * <#example#>
 * @endcode
 */
bool parcFile_Exists(const PARCFile *file);

/**
 * Create a new directory.
 *
 * @param [in] file A pointer to a `PARCFile` instance.
 * @return true if the pathname exists, false otherwise
 *
 * Example:
 * @code
 * {
 *     <#example#>
 * }
 * @endcode
 */
bool parcFile_Mkdir(const PARCFile *file);

/**
 * True if the specified `PARCFile` is an existing directory on storage.
 *
 * @param [in] file A pointer to a `PARCFile` instance.
 *
 * @return true if specified `PARCFile` is an existing directory on storage, false if not
 *
 * Example:
 * @code
 * {
 *     <#example#>
 * }
 * @endcode
 */
bool parcFile_IsDirectory(const PARCFile *file);

/**
 * Deletes the file or directory on storage.
 *
 * For a directory, it does a recursive delete.
 *
 * @param [in] file The instance of `PARCFile` to be deleted.
 * @return `true` if everything deleted, false otherwise
 *
 * Example:
 * @code
 * <#example#>
 * @endcode
 */
bool parcFile_Delete(const PARCFile *file);

/**
 * Append a representation of the specified `PARCFile` instance to the given {@link PARCBufferComposer}.
 *
 * @param [in] file A pointer to the `PARCFile` instance whose contents should be appended to to string.
 * @param [in,out] string A pointer to the `PARCBufferComposer` instance to which the contents of file will be appended.
 *
 * @return NULL Cannot allocate memory.
 * @return non-NULL The instance of `PARCBufferComposer` with the appended contents.
 *
 * Example:
 * @code
 * {
 *     PARCBufferComposer *result = parcBufferComposer_Create();
 *     PARCFile *instance = parcFile_Create("/tmp/foo");
 *
 *     parcFile_BuildString(instance, result);
 *
 *     PARCBuffer *string = parcBufferComposer_FinalizeBuffer(result);
 *     printf("File: %s\n", parcBuffer_ToString(string));
 *     parcBuffer_Release(&string);
 *
 *     parcBufferComposer_Release(&result);
 * }
 * @endcode
 */
PARCBufferComposer *parcFile_BuildString(const PARCFile *file, PARCBufferComposer *string);

/**
 * <#One Line Description#>
 *
 * <#Paragraphs Of Explanation#>
 *
 * @param [<#in#> | <#out#> | <#in,out#>] <#name#> <#description#>
 *
 * @return <#value#> <#explanation#>
 *
 * Example:
 * @code
 * {
 *     <#example#>
 * }
 * @endcode
 */
size_t parcFile_GetFileSize(const PARCFile *file);

/**
 * Create a PARCFile representation of the home directory of the current user.
 *
 * The return value must be released via `parcFile_Release`.
 *
 * @return non-NULL A pointer to a valid PARCFile instance.
 * @return NULL An error occurred.
 *
 * Example:
 * @code
 * {
 *     PARCFile *directory = parcFile_CreateHome();
 * }
 * @endcode
 */
PARCFile *parcFile_CreateHome(void);

/**
 * Produce a null-terminated string representation of the specified `PARCFile` instance.
 *
 * The non-null result must be freed by the caller via {@link parcMemory_Deallocate}.
 *
 * @param [in] file A pointer to the `PARCFile` instance.
 *
 * @return NULL Cannot allocate memory.
 * @return non-NULL A pointer to an allocated, null-terminated C string that must be deallocated via {@link parcMemory_Deallocate}.
 *
 * Example:
 * @code
 * {
 *     PARCFile *instance = parcFile_Create("/tmp/foo");
 *
 *     char *string = parcFile_ToString(instance);
 *
 *     if (string != NULL) {
 *         printf("Hello: %s\n", string);
 *         parcMemory_Deallocate((void **)&string);
 *     } else {
 *         printf("Cannot allocate memory\n");
 *     }
 *
 *     parcFile_Release(&instance);
 * }
 * @endcode
 *
 * @see {@link parcFile_BuildString}
 */
char *parcFile_ToString(const PARCFile *file);
#endif // libparc_parc_File_h