Creates a new path context from a path context and a pathname.
#include <nks/dirio.h>
int NXCreatePathContext (
NXPathCtx_t pathCtx,
const void *pathname,
NXPathFormat_t format,
void *securityBadge,
NXPathCtx_t *newPathCtx);
(IN) Specifies the file system path context. Along with pathname, this specifies the location of the new file system path context.
(IN) Points to a null-terminated Unicode or ASCII string that gives the name of the directory to be opened. It specifies an actual file system subdirectory in combination with pathCtx.
If you are creating a path context to a remote server, pathCtx must be 0 and pathname must contain at least the server name and a volume name; directory and subdirectory names are optional.
(IN) Specifies the pathname format to be used for newPathCtx. It prescribes the maximum length and legal characters of a name passed along with the path context to a function such as NXFileOpenEx or NXRename. See NXPathFormat_t Enumeration.
(IN) Points to NULL, or if you have created an identity, the identity token returned from the create_identity or the create_server_identity function. Because these functions return the identity as type int, you need to coerce it to void as demonstrated in the sample code below.
(OUT) Points to the handle of the new directory.
If successful, returns 0 and in the newPathCtx parameter, an open directory descriptor. Otherwise, returns a nonzero error code and -1 in newPathCtx.
NXCreatePathContext creates a new path context to an existing directory. The pathname parameter in combination with pathCtx specifies an actual file system subdirectory. Path contexts are completely autonomous from one another; pathCtx and newPathCtx can be freed independently from each other.
The format argument prescribes the maximum length and legal characters of a name when passed along with the path context to such functions as NXFileOpenEx or NXRename. For underlying file systems, it implies more; it implies ACL and ACL checking. These affect the information returned or set by such functions as NXGetAttr or NXDirEnumGetEntries.
The pathname format implies the following features:
Set of valid characters in a pathname
Case sensitivity of any characters (if applicable)
Length of any path element, including the file or directory name
Set of valid path separators
File system semantics, such as:
ACL format
Access control checks
Attributes
Creating a path context does not ensure that the file system entity that it points to cannot be deleted. If the directory that is referenced by the handle is deleted, any operations that are performed with it will result in an error.
To create a path context to a remote NetWare (NCP-based) file system, you must pass in an authenticated NCP connection because it is impossible to perform any I/O on the volume and server at a destination without the identity and connection. However, you cannot pass the connection, only the identity that is returned from the create_identity function. The connection is then filled in by the consuming interface (such as NXFileOpenEx). The pathCtx parameter must be 0, and the pathname parameter must include at least the server name and the volume name.
If pathCtx is not 0, format can be passed as NULL. The resulting pathname format is then inherited from pathCtx.
You do not need to hold your application to one pathname format. However, at least one path context must be created for each pathname format-specific operation, such as creating files and directories, opening, removing, renaming, getting and setting attributes, and enumerating directory entries.
int err, id;
NXPathCtx_t newCtx;
err = create_server_identity(&id);
err = NXCreatePathContext(0, "SYS:\SYSTEM", NX_PNF_DEFAULT,
(void *) id, &newCtx);