le_pathIter.h File Reference

Go to the source code of this file.

Typedefs
typedef struct le_pathIter_t *	le_pathIter_Ref_t

Functions
le_pathIter_Ref_t	le_pathIter_Create (const char *pathPtr, const char *separatorPtr, const char *parentSpecPtr, const char *currentSpecPtr)
le_pathIter_Ref_t	le_pathIter_CreateForUnix (const char *pathPtr)
le_pathIter_Ref_t	le_pathIter_Clone (le_pathIter_Ref_t originalRef)
void	le_pathIter_Delete (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_GetSeparator (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
le_result_t	le_pathIter_GetParentSpecifier (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
le_result_t	le_pathIter_GetCurrentSpecifier (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
le_result_t	le_pathIter_GetPath (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
le_result_t	le_pathIter_GoToStart (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_GoToEnd (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_GoToNext (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_GoToPrev (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_GetCurrentNode (le_pathIter_Ref_t iterRef, char *bufferPtr, size_t bufferSize)
void	le_pathIter_Truncate (le_pathIter_Ref_t iterRef)
le_result_t	le_pathIter_Append (le_pathIter_Ref_t iterRef, const char *pathStr)
bool	le_pathIter_IsAbsolute (le_pathIter_Ref_t iterRef)
bool	le_pathIter_IsEmpty (le_pathIter_Ref_t iterRef)

Detailed Description

Legato Path Iterator API include file.

Copyright (C) Sierra Wireless, Inc. 2014. All rights reserved. Use of this work is subject to 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.