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.
2026-05-29 10:13:01 +02:00
parent adf16cab28
commit 7a444c6856
1 changed files with 209 additions and 13 deletions
--- 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;