Go to the source code of this file.
Typedefs | |
typedef struct le_pathIter_t * | le_pathIter_Ref_t |
Detailed Description
Legato Path Iterator API include file.
Copyright (C) Sierra Wireless Inc. license.
Typedef Documentation
typedef struct le_pathIter_t* le_pathIter_Ref_t |
Objects of this type are used to iterate and manipulate path strings.
Function Documentation
le_result_t le_pathIter_Append | ( | le_pathIter_Ref_t | iterRef, |
const char * | pathStr | ||
) |
Take the new string path and combine it with the object's existing path.
- Note
- This function looks for the current and parent node strings and treats them specially. So, (assuming defaults,) combining the path "/a/b" with the path "../x" will give you the combined path of: "/a/x".
- Appending a non-relative path onto an existing path effectivly replaces the current path, for example, appending /a/rooted/path, onto the existing /a/seperate/path will given you the path: /a/rooted/path.
- This will automatically reset the internal iterator to point at the end of the newly formed path. Also, this function always appends to the end of a path, ignoring the current position of the iterator.
- Returns
- LE_OK if successful. LE_OVERFLOW if the output buffer is too small for the new string. LE_UNDERFLOW if combining the path the new path tries to traverse past the root. For example: "/a/b" + "../../../x" will result in LE_UNDERFLOW. However if the base path is relative, "a/b", then the resulting string will be "../x" and a return code of LE_OK.
- Parameters
-
[in] iterRef The path object to write to. [in] pathStr The new path segment to append.
le_pathIter_Ref_t le_pathIter_Clone | ( | le_pathIter_Ref_t | originalRef | ) |
Create a clone of an existing path iterator object.
- Returns
- A new path iterator object that is a duplicate of the original one.
- Parameters
-
[in] originalRef The path object to duplicate.
le_pathIter_Ref_t le_pathIter_Create | ( | const char * | pathPtr, |
const char * | separatorPtr, | ||
const char * | parentSpecPtr, | ||
const char * | currentSpecPtr | ||
) |
Create a new path iterator object. On creation, the default position of the iterator is at the end of the path.
- Returns
- A new path object setup with the given parameters.
- Parameters
-
[in] pathPtr Optional. Pointer to the inital path to use. [in] separatorPtr Required. Path separator to use. The separator can not be NULL or empty. [in] parentSpecPtr Optional. Used to traverse upwards in a path. Leave as NULL or empty to not use. This acts like how ".." is used in a filesystem path. [in] currentSpecPtr Optional. Used to refer to a current node. Much like how a '.' is used in a filesystem path.
le_pathIter_Ref_t le_pathIter_CreateForUnix | ( | const char * | pathPtr | ) |
Create a new path iterator object that is pre-configured for Unix styled paths. On creation, the default position of the iterator is at the end of the path.
The parameters are configured as follows:
- separator: "/"
- parentSpec: ".."
- currentSpec: "."
- Returns
- A new path iterator object that's ready for iterating on Unix style paths.
- Parameters
-
[in] pathPtr Optional. Create an iterator for this path, or start with an empty path.
void le_pathIter_Delete | ( | le_pathIter_Ref_t | iterRef | ) |
Delete an iterator object and free it's memory.
- Parameters
-
[in] iterRef The iterator object to destroy.
le_result_t le_pathIter_GetCurrentNode | ( | le_pathIter_Ref_t | iterRef, |
char * | bufferPtr, | ||
size_t | bufferSize | ||
) |
Get the text for the node the itrator is pointing at.
- Returns
- LE_OK if succesful. LE_OVERFLOW if the bufferPtr is too small to hold the whole string. LE_NOT_FOUND if the iterator is at the end of the path. Or if the path is empty, or simply consists of a separator.
- Parameters
-
[in] iterRef The iterator object to read. [out] bufferPtr The utf-8 formatted text buffer to write to. [in] bufferSize The size in bytes of the text buffer.
le_result_t le_pathIter_GetCurrentSpecifier | ( | le_pathIter_Ref_t | iterRef, |
char * | bufferPtr, | ||
size_t | bufferSize | ||
) |
Read the iterators string for the current node specifier. For Unix style paths for this is ".". If an empty string is used, then this is ignored for the purposes of appending and normalizing paths.
- Parameters
-
[in] iterRef The iterator object to read. [out] bufferPtr The string buffer to write to. [in] bufferSize The size of the string buffer being written to.
le_result_t le_pathIter_GetParentSpecifier | ( | le_pathIter_Ref_t | iterRef, |
char * | bufferPtr, | ||
size_t | bufferSize | ||
) |
Read the string that represents parent nodes in a path string. By for Unix style paths this is "..". If an empty string is used, then it is ignored for the purposes of appending and normalizing paths.
- Parameters
-
[in] iterRef The iterator object to read. [out] bufferPtr The string buffer to write to. [in] bufferSize The size of the buffer being written to.
le_result_t le_pathIter_GetPath | ( | le_pathIter_Ref_t | iterRef, |
char * | bufferPtr, | ||
size_t | bufferSize | ||
) |
Get a copy of the path currently contained within the iterator.
- Returns
- LE_OK if the copy is successful. LE_OVERFLOW if the buffer isn't big enough for the path string.
- Parameters
-
[in] iterRef The iterator object to read. [out] bufferPtr The string buffer to write to. [in] bufferSize The size of the buffer being written to.
le_result_t le_pathIter_GetSeparator | ( | le_pathIter_Ref_t | iterRef, |
char * | bufferPtr, | ||
size_t | bufferSize | ||
) |
Read the string that is being used to represent path separators in this iterator object.
- Parameters
-
[in] iterRef The iterator object to read. [out] bufferPtr The string buffer to write to. [in] bufferSize The size of the buffer being written to.
le_result_t le_pathIter_GoToEnd | ( | le_pathIter_Ref_t | iterRef | ) |
Jump the iterator to the end of the path.
- Returns
- LE_OK if the move was successful. LE_NOT_FOUND if the path is empty, or only contains a separator.
- Parameters
-
[in] iterRef The iterator object to update.
le_result_t le_pathIter_GoToNext | ( | le_pathIter_Ref_t | iterRef | ) |
Move to the next node in the path.
- Returns
- LE_OK if the itrator was successful in jumping to the next node. LE_NOT_FOUND is returned if there are no more nodes to move to in the path.
- Parameters
-
[in] iterRef The iterator object to update.
le_result_t le_pathIter_GoToPrev | ( | le_pathIter_Ref_t | iterRef | ) |
Move to the previous node in the path.
- Returns
- LE_OK if the iterator was successfuly moved, LE_NOT_FOUND if there are no prior nodes to move to.
- Parameters
-
[in] iterRef The iterator object to update.
le_result_t le_pathIter_GoToStart | ( | le_pathIter_Ref_t | iterRef | ) |
Jump the iterator to the beginning of the path.
- Returns
- LE_OK if the move was successful. LE_NOT_FOUND if the path is empty, or only contains a separator.
- Parameters
-
[in] iterRef The iterator object to update.
bool le_pathIter_IsAbsolute | ( | le_pathIter_Ref_t | iterRef | ) |
Is this an absolute or relative path?
- Returns
- True if the path is absolute, that is that it begins with a separator. False if the path is considered relative.
- Parameters
-
[in] iterRef The iterator object to read.
bool le_pathIter_IsEmpty | ( | le_pathIter_Ref_t | iterRef | ) |
Is the path object holding an empty string?
- Returns
- True if the path is empty, false if not.
- Parameters
-
iterRef The path object to read.
void le_pathIter_Truncate | ( | le_pathIter_Ref_t | iterRef | ) |
Truncate the path at the current iterator node. If the iterator is at the beginning of the path, then the whole path is cleared. If the iterator is at the end of the path, then nothing happens.
Once done, then the iterator will be pointing at the new end of the path.
- Parameters
-
[in] iterRef The iterator to update.