From 7a444c6856a16f93a5d489c04e29355174984d59 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Fri, 29 May 2026 10:13:01 +0200 Subject: [PATCH] ncpcalls: document low-level NCP wrappers Add function-level comments to the low-level NCP wrapper functions in ncpcall.c. Document each wrapper's purpose, NCP function/subfunction, requester path and return behavior. The descriptions are based on the existing implementation and cross-checked against the MARS-NWE admin sources and Novell SDK/WebSDK references. No behavior change. --- ncpcall.c | 222 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 209 insertions(+), 13 deletions(-) diff --git a/ncpcall.c b/ncpcall.c index ac2e850..42feee0 100644 --- a/ncpcall.c +++ b/ncpcall.c @@ -26,14 +26,31 @@ #include "net.h" /* ---------------- 0x16 ----------------------------------- */ +/* + * ncp16_02_get_directory_entry + * + * Purpose: + * Looks up a directory entry relative to a NetWare directory handle and + * returns the canonical subdirectory name, creation timestamp, owner object + * ID, subdirectory number and maximum rights mask. + * + * NCP: + * Function 0x16, subfunction 0x02. MARS-NWE admin documents this old + * filesystem call as Scan Directory Information / Get Directory Entry + * (F216/02). + * + * Requester path: + * Net_Call(0xE200), with a 16-bit request and reply length prefix. + * + * Returns: + * Maximum rights mask on success, or -1 when the requester/NCP call fails. + */ int ncp16_02_get_directory_entry(int dirhandle, uint8 *path, int *sub_dir, uint8 *resultpath, uint32 *creattime, uint32 *owner_id) - -/* returns max. rights or -1 if failed */ { struct { uint16 len; @@ -68,8 +85,23 @@ int ncp16_02_get_directory_entry(int dirhandle, } /* ---------------- 0x17 ----------------------------------- */ +/* + * ncp17_02_set_debug_level + * + * Purpose: + * Sets a MARS-NWE debug level for one server module and returns the previous + * debug value. This is a MARS-NWE helper, not a normal Novell client command. + * + * NCP: + * Function group 0x17, subfunction 0x02. + * + * Requester path: + * Net_Call(0xE300), with a 16-bit request and reply length prefix. + * + * Returns: + * Previous debug level on success, or -1 when the requester/NCP call fails. + */ int ncp17_02_set_debug_level(int module, int debuglevel) -/* debuglevel fuer module setzen */ { struct { uint16 len; @@ -89,8 +121,25 @@ int ncp17_02_set_debug_level(int module, int debuglevel) return((int) repl.olddebug); } +/* + * ncp17_14_login_object_unencrypted + * + * Purpose: + * Logs in a bindery object using the legacy unencrypted password call. + * + * NCP: + * Function group 0x17, subfunction 0x14. This is the older unencrypted login + * path; encrypted login normally uses the key returned by subfunction 0x17 + * and the keyed-login call below. + * + * Requester path: + * Net_Call(0xE300), with object type, counted object name and counted + * password in the request body. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_14_login_object_unencrypted(uint8 *objname, uint16 objtyp, uint8 *password) -/* login unencreypted */ { struct { uint16 len; @@ -116,8 +165,23 @@ int ncp17_14_login_object_unencrypted(uint8 *objname, uint16 objtyp, uint8 *pass return(0); } +/* + * ncp17_17_get_encryption_key + * + * Purpose: + * Retrieves the 8-byte login encryption key used by the legacy bindery + * encrypted login and password-change helpers. + * + * NCP: + * Function group 0x17, subfunction 0x17. + * + * Requester path: + * Net_Call(0xE300). The reply contains the raw 8-byte key. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_17_get_encryption_key(uint8 *key) -/* get crypt key */ { struct { uint16 len; @@ -138,8 +202,23 @@ int ncp17_17_get_encryption_key(uint8 *key) } } +/* + * ncp17_18_keyed_object_login + * + * Purpose: + * Performs keyed/encrypted bindery object login using the 8-byte challenge + * returned by ncp17_17_get_encryption_key(). + * + * NCP: + * Function group 0x17, subfunction 0x18. + * + * Requester path: + * Net_Call(0xE300), with key, object type and counted object name. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_18_keyed_object_login(uint8 *cryptkey, uint8 *objname, uint16 objtyp) -/* keyed login */ { struct { uint16 len; @@ -163,8 +242,24 @@ int ncp17_18_keyed_object_login(uint8 *cryptkey, uint8 *objname, uint16 objtyp) return(0); } +/* + * ncp17_35_get_bindery_object_id + * + * Purpose: + * Resolves a bindery object name and type to its 32-bit object ID. The + * canonical object name returned by the server is copied back to objname. + * + * NCP: + * Function group 0x17, subfunction 0x35, Get Bindery Object ID + * (MARS-NWE admin: F217/35; Novell SDK/WebSDK: Get Bindery Object ID). + * + * Requester path: + * Net_Call(0xE300), with big-endian object type and counted object name. + * + * Returns: + * Object ID on success, or 0 when the requester/NCP call fails. + */ uint32 ncp17_35_get_bindery_object_id(uint8 *objname, uint16 objtyp) -/* get bindery object id */ { struct { uint16 len; @@ -191,8 +286,23 @@ uint32 ncp17_35_get_bindery_object_id(uint8 *objname, uint16 objtyp) return(GET_BE32(repl.object_id)); } +/* + * ncp17_36_get_bindery_object_name + * + * Purpose: + * Resolves a 32-bit bindery object ID to its object name and type. + * + * NCP: + * Function group 0x17, subfunction 0x36, Get Bindery Object Name + * (MARS-NWE admin: F217/36; Novell SDK/WebSDK: Get Bindery Object Name). + * + * Requester path: + * Net_Call(0xE300), with the object ID in big-endian order. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_36_get_bindery_object_name(uint32 obj_id, uint8 *objname, uint16 *objtyp) -/* get bindery object name */ { struct { uint16 len; @@ -217,9 +327,26 @@ int ncp17_36_get_bindery_object_name(uint32 obj_id, uint8 *objname, uint16 *objt } +/* + * ncp17_40_change_password_unencrypted + * + * Purpose: + * Changes a bindery object's password using the legacy unencrypted password + * call. + * + * NCP: + * Function group 0x17, subfunction 0x40, Change Bindery Object Password + * (MARS-NWE admin: F217/40). + * + * Requester path: + * Net_Call(0xE300), with object type, counted object name, counted old + * password and counted new password. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_40_change_password_unencrypted(uint8 *objname, uint16 objtyp, uint8 *password, uint8 *newpassword) -/* change password unencreypted */ { struct { uint16 len; @@ -249,8 +376,25 @@ int ncp17_40_change_password_unencrypted(uint8 *objname, uint16 objtyp, return(0); } +/* + * ncp14_46_get_bindery_access_level + * + * Purpose: + * Reads the current bindery access level and the logged-in object's object ID. + * + * NCP: + * Bindery subfunction 0x46, Get Bindery Access Level. The historic local + * wrapper was named ncp_14_46; keep the ncp14_ prefix to preserve that + * protocol reference even though the call is sent through Net_Call(0xE300). + * + * Requester path: + * Net_Call(0xE300). The reply contains one access byte followed by the + * current object's 32-bit object ID in big-endian order. + * + * Returns: + * Access level on success, or -1 when the requester/NCP call fails. + */ int ncp14_46_get_bindery_access_level(uint32 *obj_id) -/* get bindery access level & actual ID */ { struct { uint16 len; @@ -273,9 +417,26 @@ int ncp14_46_get_bindery_access_level(uint32 *obj_id) } +/* + * ncp17_4b_keyed_change_password + * + * Purpose: + * Changes a bindery object's password using the keyed/encrypted password + * change path. + * + * NCP: + * Function group 0x17, subfunction 0x4b, Change Encrypted Bindery Object + * Password (MARS-NWE admin: F217/4B). + * + * Requester path: + * Net_Call(0xE300), with the login encryption key, object type, counted + * object name, password length selector and encrypted new password bytes. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_4b_keyed_change_password(uint8 *cryptkey, uint8 *objname, uint16 objtyp, int passwx, uint8 *newpassword) -/* keyed change password */ { struct { uint16 len; @@ -304,9 +465,27 @@ int ncp17_4b_keyed_change_password(uint8 *cryptkey, uint8 *objname, uint16 objty } +/* + * ncp17_37_scan_bindery_object + * + * Purpose: + * Iterates over bindery objects matching an object type and name pattern. + * Pass last_id as -1 for the first call and then feed back the object ID + * returned in target to continue scanning. + * + * NCP: + * Function group 0x17, subfunction 0x37, Scan Bindery Object + * (MARS-NWE admin: F217/37; Novell SDK/WebSDK: Scan Bindery Object). + * + * Requester path: + * Net_Call(0xE300), with last object ID, search object type and counted + * pattern. A NULL pattern is sent as '*'. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_37_scan_bindery_object(uint32 last_id, uint16 objtyp, uint8 *pattern, BINDERY_OBJECT *target) -/* scan bindery object */ { struct { uint16 len; @@ -356,9 +535,26 @@ int ncp17_37_scan_bindery_object(uint32 last_id, uint16 objtyp, uint8 *pattern, return(0); } +/* + * ncp17_3d_read_property_value + * + * Purpose: + * Reads one 128-byte segment of a bindery property value and returns the + * server's continuation and property flags. + * + * NCP: + * Function group 0x17, subfunction 0x3d, Read Property Value + * (MARS-NWE admin: F217/3D; Novell SDK/WebSDK: Read Property Value). + * + * Requester path: + * Net_Call(0xE300), with object type, counted object name, segment number + * and counted property name. + * + * Returns: + * 0 on success, or -1 when the requester/NCP call fails. + */ int ncp17_3d_read_property_value(uint16 objtyp, uint8 *objname, int segment, uint8 *propname, NW_PROPERTY *target) -/* read bindery property value */ { struct { uint16 len;