NWCLIENT.C

Client oriented API for ncpfs

Purpose:

In order to simplify coding of tree/context oriented utilities, we embarked in this high level library project using name of functions similar to those used in Netware NDK (NWCX*). Many of the functions here are ncpfs specific (permament connections, environnment variables...)

Requirements:

ncpfs version 2.2 installed and operational (slist) on the Linux box.
To compile or modify this library you should install the ncp headers files in /usr/include by running make install-dev in your current ncpfs main distribution directory.

Conventions:

ncpfs API is quite extensive and functions are spread in several libraries (ipxlib, ncp, ndslib, nwnet, ncplib, nwcalls and nwfse ). When naming an API function, we will prepend the name of the library , so nwnet/NwIsDsServer means the function NWIsDsServer from lib/nwnet.c

API purpose examples, caveats...

int NWCXIsDSServer ( NWCONN_HANDLE conn, NWDSChar * treeName); Returns 1 (Ok) if server associated with connection conn is a DS server (Netware >3). In that case treeName will contains its NDS tree name (with trailings '_' removed). This is a convenience function calling nwnet/NWIsDsServer
Caution: to follow the nwnet/NWIsDSServer convention all NWCXIs* fonctions return non zero if OK

int NWCXIsSameTree (NWCONN_HANDLE conn, const NWDSChar *treeName) ; Returns 1 (Ok) if server associated with connection conn is a DS server and belongs to the tree specified in treeName

int NWCXIsSameServer(NWCONN_HANDLE conn, const NWDSChar* server); Returns 1 (Ok) if server associated with connection conn is the same as the server specified in parameter server

NWCCODE NWCXIsPermanentConnection (NWCONN_HANDLE conn); Returns 1 (Ok) if the connection conn is a permanent connection; that is has been opened using ncpmount/ncplogin and has an entry in /etc/mtab.

NWDSCCODE NWCXIsDSAuthenticated(NWDSContextHandle ctx); Returns 1 (Ok) if the context holds authentication keys; that if one of its connection is permanent and has authentication tokens stored in private data. This is the 'key fonction' for ncpmap. If the context has authentication keys, we can retrieve them to access other Netware ressources belonging to the same tree whitout asling again for login/password.

The four following functions are an attempt to simplify usage of command lines utilities by fetching in environnment arguments missing from the command line.
We are using the same env names as the Caldera client (hope they won't mind):

NWCLIENT_PREFERRED_TREE NWCLIENT_DEFAULT_NAME_CONTEXT NWCLIENT_PREFERRED_SERVER NWCLIENT_DEFAULT_USER NWCLIENT_DEFAULT_PASSWORD this one is an extra by PP for a possible autologon
We recommend that on every workstation you set at least the 2 first values in system wide /etc/profile. as follow:

NWCLIENT_PREFERRED_TREE=INSA_ROOT <-- change to match your tree NWCLIENT_DEFAULT_NAME_CONTEXT=PC <-- change to match defualt context NWCLIENT_DEFAULT_USER=$USER <-- Unix login is normally the same as Netware login (you may later adjust for individual user such as root in their ~/.bash_profile file. export NWCLIENT_PREFERRED_TREE export NWCLIENT_DEFAULT_NAME_CONTEXT export NWCLIENT_DEFAULT_USER
If nothing is found in current's user environnment, these functions search into the file ~/.nwinfos that is created by the PAM module.
TODO
NWDSCCODE NWCXGetPreferredDSTree (NWDSChar * preferTree, size_t maxLen);

NWDSCCODE NWCXGetDefaultNameContext (const NWDSChar* treeName,NWDSChar * nameContext, size_t maxLen);

NWDSCCODE NWCXGetPreferredServer (const NWDSChar * forTree,NWDSChar *preferedServer, size_t maxLen);

NWDSCCODE NWCXGetDefaultUserName (const NWDSChar * forTree,NWDSChar *defaultName, size_t maxLen); TODO

NWDSCCODE NWCXGetDefaultPassword (const NWDSChar * forTree,NWDSChar *defaultPwd, size_t maxLen);

NWCCODE NWCXGetPermConnList (NWCONN_HANDLE* conns , int maxEntries, int* curEntries, uid_t uid); returns the list of permanent connexions belonging to user uid. If uid=-1 = all Permanent connections (Root only can call it) main function used in ncplogout (that replaces ncpumount in recent releases)
caller must pass a suitable array of NWCONN_HANDLE and its size.

NWCCODE NWCXGetPermConnListByTreeName (NWCONN_HANDLE* conns, int maxEntries, int* curEntries, uid_t uid, const NWDSChar *treeName); same as above but limiting connections to those related to tree treeName. function used in ncplogout
caller must pass a suitable array of NWCONN_HANDLE and its size.

NWCCODE NWCXGetPermConnListByServerName (NWCONN_HANDLE* conns , int maxEntries, int* curEntries, uid_t uid, const NWDSChar *serverName); same as above but limiting connections to those related to server serverName. function used in ncplogout
caller must pass a suitable array of NWCONN_HANDLE and its size.

NWDSCCODE NWDSCreateContextHandleMnt(NWDSContextHandle* ctx, const NWDSChar * treeName); create a context,add to it all permanent connections related to treeName and belonging to me (by using getuid())
Key function used in ncplogin, ncpmap to check if current user is already authenticated to to target tree or server.
Normally this function do not open any new connection, but retrieves already active ones.

NWDSCCODE NWDSFreeContextHandleMnt(NWDSContextHandle ctx, const NWDSChar * treeName); free a context created by NWDSCreateContextHandleMnt (still experimental, not released)

NWDSCCODE NWCXAttachToTreeByName( NWCONN_HANDLE* conn, const NWDSChar * treeName); open an unauthenticated connection to the first visible server belonging to treeName Was using nwnet/NWScanForAvailableTrees in ncpfs <2.2.0.11, now use the API nwcalls/NWCCOpenConnByName(NULL, treeName, NWCC_NAME_FORMAT_NDS_TREE, NWCC_OPEN_NEW_CONN,NWCC_RESERVED, conn);

misc NDS properties reading functions to alleviate writing future utilities
Mostly used for now in ncpwhoami

NWDSCCODE NWCXGetNDSVolumeServerAndResourceName(NWDSContextHandle ctx,const NWDSChar* ndsName, NWDSChar* serverName, size_t serverNameMaxLen, NWDSChar *resourceName, size_t resourceNameMaxlen); return server name (DN or RN) and volume name of a NDS volume You may pass NULL for serverName or resourceName if not interested by the information.

NWDSCCODE NWCXGetObjectHomeDirectory(NWDSContextHandle ctx, const NWDSChar* ndsName, NWDSChar* serverName, size_t serverNameMaxLen, NWDSChar *resourceName, size_t resourceNameMaxLen, NWDSChar* NDSvolumeName, size_t NDSVolumeNameMaxLen, NWDSChar* pathName, size_t pathNameMaxLen); return the home directory of user's ndsName splitted in three parts: server name, volume name and path
You may pass NULL if not interested by one of the three information

NWDSCCODE NWCXGetObjectLastLoginTime(NWDSContextHandle ctx, const NWDSChar* ndsName, time_t * tm); return the last login time of user's ndsName

NWDSCCODE NWCXGetObjectMessageServer(NWDSContextHandle ctx, const NWDSChar* ndsName, NWDSChar* serverName, int serverNameMaxLen); return the name of the message server ( aka preferred server) associated with user ndsName

NWDSCCODE NWCXGetObjectLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len, int maxlen); return the object login script of user's ndsName in buffer and its length in len. For an example see ncpwhoami -f0

NWDSCCODE NWCXGetContextLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len,int maxlen); return the context login script of user's ndsName in buffer and its length in len.
This function will climb up contexts from user's context until a match is found. For an example see ncpwhoami -f1

NWDSCCODE NWCXGetProfileLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len, int maxlen); return the profile login script associated with user's ndsName in buffer and its length in len.
This function will first check if user has an assocaited profile and try to read its login script. For an example see ncpwhoami -f2

NWDSCCODE NWCXGetStringAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char* buffer, int maxlen); read a NDS String single valued attribute.
Multivalued attributes and others syntaxes (numeric, time, boolean...) returns an error. For example see nds_read functions in PHP or Java modules.
the PAM module uses lower level calls to fetch more than one attribute at a time.

NWDSCCODE NWCXGetIntAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, int * value); read a NDS numeric valued attribute as a integer.
This fonction process Counter, numeric, interval boolean and time syntaxes. Others syntaxes (String, Multivalued attributes...) returns an error. For example see nds_read functions in PHP or Java modules.

NWDSCCODE NWCXGetAttributeValueAsString (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char* buffer, size_t maxlen); read a NDS single valued attribute.
String attributes are returned intact
Boolean attributes are returned as true/false
Time attributes are returned as a locatized time string
Numeric attributes are converted to a string
Multivalued attributes returns an error. For example see nds_read functions in PHP or Java modules.

NWDSCCODE NWCXGetMultiStringAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char** buffer) ; read a multi valued string attribute and returns its value in a comma separted list. caution : caller MUST free the buffer created here For example see nds_read functions in PHP or Java modules.

NWDSCCODE NWCXSplitNameAndContext (NWDSContextHandle ctx,const NWDSChar * dn, char * name, char* context); split a FQDN NDS name to name and context.
To get name only, pass NULL as context
To get context only pass NULL as name
Context flags (TYPELESS_NAMES...)are honored.

API	purpose	examples, caveats...
int NWCXIsDSServer ( NWCONN_HANDLE conn, NWDSChar * treeName);	Returns 1 (Ok) if server associated with connection conn is a DS server (Netware >3). In that case treeName will contains its NDS tree name (with trailings '_' removed).	This is a convenience function calling nwnet/NWIsDsServer Caution: to follow the nwnet/NWIsDSServer convention all NWCXIs* fonctions return non zero if OK
int NWCXIsSameTree (NWCONN_HANDLE conn, const NWDSChar *treeName) ;	Returns 1 (Ok) if server associated with connection conn is a DS server and belongs to the tree specified in treeName
int NWCXIsSameServer(NWCONN_HANDLE conn, const NWDSChar* server);	Returns 1 (Ok) if server associated with connection conn is the same as the server specified in parameter server
NWCCODE NWCXIsPermanentConnection (NWCONN_HANDLE conn);	Returns 1 (Ok) if the connection conn is a permanent connection; that is has been opened using ncpmount/ncplogin and has an entry in /etc/mtab.
NWDSCCODE NWCXIsDSAuthenticated(NWDSContextHandle ctx);	Returns 1 (Ok) if the context holds authentication keys; that if one of its connection is permanent and has authentication tokens stored in private data.	This is the 'key fonction' for ncpmap. If the context has authentication keys, we can retrieve them to access other Netware ressources belonging to the same tree whitout asling again for login/password.
The four following functions are an attempt to simplify usage of command lines utilities by fetching in environnment arguments missing from the command line. We are using the same env names as the Caldera client (hope they won't mind): NWCLIENT_PREFERRED_TREE NWCLIENT_DEFAULT_NAME_CONTEXT NWCLIENT_PREFERRED_SERVER NWCLIENT_DEFAULT_USER NWCLIENT_DEFAULT_PASSWORD this one is an extra by PP for a possible autologon We recommend that on every workstation you set at least the 2 first values in system wide /etc/profile. as follow: NWCLIENT_PREFERRED_TREE=INSA_ROOT <-- change to match your tree NWCLIENT_DEFAULT_NAME_CONTEXT=PC <-- change to match defualt context NWCLIENT_DEFAULT_USER=$USER <-- Unix login is normally the same as Netware login (you may later adjust for individual user such as root in their ~/.bash_profile file. export NWCLIENT_PREFERRED_TREE export NWCLIENT_DEFAULT_NAME_CONTEXT export NWCLIENT_DEFAULT_USER If nothing is found in current's user environnment, these functions search into the file ~/.nwinfos that is created by the PAM module. TODO
NWDSCCODE NWCXGetPreferredDSTree (NWDSChar * preferTree, size_t maxLen);
NWDSCCODE NWCXGetDefaultNameContext (const NWDSChar* treeName,NWDSChar * nameContext, size_t maxLen);
NWDSCCODE NWCXGetPreferredServer (const NWDSChar * forTree,NWDSChar *preferedServer, size_t maxLen);
NWDSCCODE NWCXGetDefaultUserName (const NWDSChar * forTree,NWDSChar *defaultName, size_t maxLen);		TODO
NWDSCCODE NWCXGetDefaultPassword (const NWDSChar * forTree,NWDSChar *defaultPwd, size_t maxLen);
NWCCODE NWCXGetPermConnList (NWCONN_HANDLE* conns , int maxEntries, int* curEntries, uid_t uid);	returns the list of permanent connexions belonging to user uid. If uid=-1 = all Permanent connections (Root only can call it)	main function used in ncplogout (that replaces ncpumount in recent releases) caller must pass a suitable array of NWCONN_HANDLE and its size.
NWCCODE NWCXGetPermConnListByTreeName (NWCONN_HANDLE* conns, int maxEntries, int* curEntries, uid_t uid, const NWDSChar *treeName);	same as above but limiting connections to those related to tree treeName.	function used in ncplogout caller must pass a suitable array of NWCONN_HANDLE and its size.
NWCCODE NWCXGetPermConnListByServerName (NWCONN_HANDLE* conns , int maxEntries, int* curEntries, uid_t uid, const NWDSChar *serverName);	same as above but limiting connections to those related to server serverName.	function used in ncplogout caller must pass a suitable array of NWCONN_HANDLE and its size.
NWDSCCODE NWDSCreateContextHandleMnt(NWDSContextHandle* ctx, const NWDSChar * treeName);	create a context,add to it all permanent connections related to treeName and belonging to me (by using getuid())	Key function used in ncplogin, ncpmap to check if current user is already authenticated to to target tree or server. Normally this function do not open any new connection, but retrieves already active ones.
NWDSCCODE NWDSFreeContextHandleMnt(NWDSContextHandle ctx, const NWDSChar * treeName);	free a context created by NWDSCreateContextHandleMnt	(still experimental, not released)
NWDSCCODE NWCXAttachToTreeByName( NWCONN_HANDLE* conn, const NWDSChar * treeName);	open an unauthenticated connection to the first visible server belonging to treeName	Was using nwnet/NWScanForAvailableTrees in ncpfs <2.2.0.11, now use the API nwcalls/NWCCOpenConnByName(NULL, treeName, NWCC_NAME_FORMAT_NDS_TREE, NWCC_OPEN_NEW_CONN,NWCC_RESERVED, conn);
misc NDS properties reading functions to alleviate writing future utilities Mostly used for now in ncpwhoami
NWDSCCODE NWCXGetNDSVolumeServerAndResourceName(NWDSContextHandle ctx,const NWDSChar* ndsName, NWDSChar* serverName, size_t serverNameMaxLen, NWDSChar *resourceName, size_t resourceNameMaxlen);	return server name (DN or RN) and volume name of a NDS volume	You may pass NULL for serverName or resourceName if not interested by the information.
NWDSCCODE NWCXGetObjectHomeDirectory(NWDSContextHandle ctx, const NWDSChar* ndsName, NWDSChar* serverName, size_t serverNameMaxLen, NWDSChar resourceName, size_t resourceNameMaxLen, NWDSChar NDSvolumeName, size_t NDSVolumeNameMaxLen, NWDSChar* pathName, size_t pathNameMaxLen);	return the home directory of user's ndsName splitted in three parts: server name, volume name and path	You may pass NULL if not interested by one of the three information
NWDSCCODE NWCXGetObjectLastLoginTime(NWDSContextHandle ctx, const NWDSChar* ndsName, time_t * tm);	return the last login time of user's ndsName
NWDSCCODE NWCXGetObjectMessageServer(NWDSContextHandle ctx, const NWDSChar* ndsName, NWDSChar* serverName, int serverNameMaxLen);	return the name of the message server ( aka preferred server) associated with user ndsName
NWDSCCODE NWCXGetObjectLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len, int maxlen);	return the object login script of user's ndsName in buffer and its length in len.	For an example see ncpwhoami -f0
NWDSCCODE NWCXGetContextLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len,int maxlen);	return the context login script of user's ndsName in buffer and its length in len. This function will climb up contexts from user's context until a match is found.	For an example see ncpwhoami -f1
NWDSCCODE NWCXGetProfileLoginScript(NWDSContextHandle ctx,const NWDSChar* objectName, char* buffer, int * len, int maxlen);	return the profile login script associated with user's ndsName in buffer and its length in len. This function will first check if user has an assocaited profile and try to read its login script.	For an example see ncpwhoami -f2
NWDSCCODE NWCXGetStringAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char* buffer, int maxlen);	read a NDS String single valued attribute. Multivalued attributes and others syntaxes (numeric, time, boolean...) returns an error.	For example see nds_read functions in PHP or Java modules. the PAM module uses lower level calls to fetch more than one attribute at a time.
NWDSCCODE NWCXGetIntAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, int * value);	read a NDS numeric valued attribute as a integer. This fonction process Counter, numeric, interval boolean and time syntaxes. Others syntaxes (String, Multivalued attributes...) returns an error.	For example see nds_read functions in PHP or Java modules.
NWDSCCODE NWCXGetAttributeValueAsString (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char* buffer, size_t maxlen);	read a NDS single valued attribute. String attributes are returned intact Boolean attributes are returned as true/false Time attributes are returned as a locatized time string Numeric attributes are converted to a string Multivalued attributes returns an error.	For example see nds_read functions in PHP or Java modules.
NWDSCCODE NWCXGetMultiStringAttributeValue (NWDSContextHandle ctx, const NWDSChar* objectName, const NWDSChar* attrName, char** buffer) ;	read a multi valued string attribute and returns its value in a comma separted list.	caution : caller MUST free the buffer created here For example see nds_read functions in PHP or Java modules.
NWDSCCODE NWCXSplitNameAndContext (NWDSContextHandle ctx,const NWDSChar * dn, char * name, char* context);	split a FQDN NDS name to name and context. To get name only, pass NULL as context To get context only pass NULL as name	Context flags (TYPELESS_NAMES...)are honored.

Download:

nwclient.c release in included in current ncpfs package.

History:

	1.00  2001, Feb 18		Patrick Pollet
		Initial release.

        1.01  2001, March 9		Patrick Pollet
                Removed NWDSScanConnsForTrees.Is now in nwnet.c
		Corrected NWCXGetPermConnInfo(NWCC_INFO_AUTHENT_STATE).
                Corrected NWCXSplitNameAndContext (had no return values)

	1.02  2001, March 12		Patrick Pollet
                #131:Corrected NWCXIsDSAuthenticated ( return 0 if not dxh) and not -1
                #137:__NWCXGetPermConnList made static ( now internal only ?)
                #341: added tests for null pointers in NWCXAttachToTreeByName,NWCXGetDefault*
                #389: better error code NWE_BIND_NO_SUCH_PROP
                NWCXGetNDSVolumeServerAndResourceName now allows null pointers for serverName/resourceName

	1.03  2001, March 16		Patrick Pollet
		#284 (NWDSCreateContextHandleMnt): added missing NWDSFreeContext
		Rewrote the attribute reading part
		Added NWCXGetIntAttributeValues, NWCXGetStringAttributeValues,
                	NWCXGetMultiStringAttributeValues, NWCXGetAttributeValuesAsString,
                Added reading the ~/.nwinfos file to fetch default tree, ctx, user if none in environnment
                Added NWCXGetDefaultServer call to NWCXAttachToTreeByName()

	1.04  2001, May 31		Petr Vandrovec 
		Add include strings.h, use ncpt_atomic_*, not atomic_*,
		use size_t for size...

	1.05  2001, July 15		Petr Vandrovec 
		Fixed NWCXSplitNameAndContext to honor ctx's settings.

	1.06  2001, October 21		Patrick.Pollet@insa-lyon.fr
		Fixed NWCXSplitNameAndContext to allow NULL name or context .
		Mofified NWCXAttachToTreeByName() to use the new NWCCOpenConnByname((,,NWCC_NAME_FORMAT_NDS_TREE,...)

	1.07  2001, December 7		Patrick.Pollet@insa-lyon.fr
		Reverted NWCXAttachToTreeByName() to use the old code since (see #define USE_OLD_CODE)
		new NWCCOpenConnByname((,,NWCC_NAME_FORMAT_NDS_TREE,...) is sometimes capricious

	1.08  2002, January 20		Petr Vandrovec 
		Moved NWCC_INFO_MOUNT_POINT code from here to nwcalls.c.
		Compile portions need by ncpumount even when NDS_SUPPORT is disabled.

	1.09  2002, January 25		Patrick.Pollet@insa-lyon.fr
		Implemented LoginScript reading API calls
                          Removed NWDSAbbreviateName in  __docopy_string when retrieving a SYN_DIST_NAME

	1.10  2003, January 12		Patrick.Pollet@insa-lyon.fr
		Reverted NWCXAttachToTreeByName() to use new NWCCOpenConnByname((,,NWCC_NAME_FORMAT_NDS_TREE,...)

	1.11  2003, January 13		Patrick.Pollet@insa-lyon.fr  (not released)
		Tracking down the extra connection with ncplogin #define PP_13_01_2003
		-added NWDSCCODE NWDSFreeContextHandleMnt(NWDSContextHandle* ctx, const NWDSChar * treeName)
		that close the connections opened by NWDSCCODE NWDSCreateContextHandleMnt(NWDSContextHandle* ctx, const NWDSChar * treeName)

TODO:

We noticed a bit too late that ncpfs has a "global configuration file "/etc/ncpfs.conf." and honor a ~./nwclient per user directory. So maybe the defaut tree, default context and default server should also be searched in the [requester] section of these files.
NWCXAttachToTreeByName should check that treeName is not a permanent mount point (starting with /). In that case it should call ncp_open_mount instead of searching the network and opening a new connection. This is done in most clients ( PAM, PHP, java...) but doing it here would be simpler.
NWCXGetDefaultUserName should return current user's Unix name if nothing found in environnment nor in config files. that will remove the need of the line NWCLIENT_DEFAULT_USER=$USER if /etc/profile

Vous �tes notre eme visiteur