mars_nwe/mars-dosutils
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

c32ncp: document NCP API wrapper functions

Browse Source 
Add function-level comments to the NCP API wrappers in c32ncp.c.

Document the local packet helpers, Client32/Raw5 handle-path setup, NCP87
entry information and DOS information calls, effective rights lookup,
trustee-related NCP22/NCP87 wrappers, and the experimental NCP87/01,
NCP74 and NCP66 helpers used by the NCOPY investigation.

The comments are written so the file can later be renamed to ncpapi.c without
changing the documented API purpose.

No behavior change.
This commit is contained in:
Mario Fetka
2026-05-29 10:57:57 +02:00
parent 7c1499a16c
commit e7f67fa004
1 changed files with 294 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

294
c32ncp.c
View File

@@ -26,12 +26,30 @@
#include "c32ncp.h"
/* c32ncp.c - namespace/file-system NCP API helpers for mars-dosutils */
/*
* c32_put_word_lh
*
* Purpose:
* Writes a 16-bit little-endian value into a request buffer.
*
* Notes:
* This file will later become ncpapi.c. These local helpers remain here
* for now so the NCP API wrappers keep their packet construction isolated
* from the more general tools.c helpers.
*/
static void c32_put_word_lh(uint8 *p, uint16 v)
{
p[0] = (uint8)(v & 0xff);
p[1] = (uint8)((v >> 8) & 0xff);
}
/*
* c32_put_dword_lh
*
* Purpose:
* Writes a 32-bit little-endian value into a request buffer.
*/
static void c32_put_dword_lh(uint8 *p, uint32 v)
{
p[0] = (uint8)(v & 0xff);
@@ -40,6 +58,16 @@ static void c32_put_dword_lh(uint8 *p, uint32 v)
p[3] = (uint8)((v >> 24) & 0xff);
}
/*
* c32_put_dword_hl
*
* Purpose:
* Writes a 32-bit high-low value into a request buffer.
*
* Notes:
* Some older file and trustee NCPs use high-low object ids or offsets even
* when the surrounding NCP87 fields are little-endian.
*/
static void c32_put_dword_hl(uint8 *p, uint32 v)
{
p[0] = (uint8)((v >> 24) & 0xff);
@@ -48,11 +76,23 @@ static void c32_put_dword_hl(uint8 *p, uint32 v)
p[3] = (uint8)(v & 0xff);
}
/*
* c32_get_word_lh
*
* Purpose:
* Reads a 16-bit little-endian value from a reply buffer.
*/
static uint16 c32_get_word_lh(uint8 *p)
{
return((uint16)(p[0] | ((uint16)p[1] << 8)));
}
/*
* c32_get_dword_lh
*
* Purpose:
* Reads a 32-bit little-endian value from a reply buffer.
*/
static uint32 c32_get_dword_lh(uint8 *p)
{
return((uint32)p[0] |
@@ -61,6 +101,12 @@ static uint32 c32_get_dword_lh(uint8 *p)
((uint32)p[3] << 24));
}
/*
* c32_get_dword_hl
*
* Purpose:
* Reads a 32-bit high-low value from a reply buffer.
*/
static uint32 c32_get_dword_hl(uint8 *p)
{
return(((uint32)p[0] << 24) |
@@ -69,6 +115,20 @@ static uint32 c32_get_dword_hl(uint8 *p)
(uint32)p[3]);
}
/*
* c32_build_handle_path
*
* Purpose:
* Builds the Client32-compatible NWHandlePathStruct used by NCP87 request
* wrappers when the caller already has one to three path components.
*
* Parameters:
* dhandle/dirbase/style describe the starting directory context. c1..c3
* are written as length-prefixed path components.
*
* Returns:
* Number of bytes used by the path structure.
*/
static UI c32_build_handle_path(uint8 *buf, uint8 dhandle,
uint16 dirbase, uint8 style,
int count,
@@ -138,6 +198,17 @@ static UI c32_build_handle_path(uint8 *buf, uint8 dhandle,
}
/*
* c32_build_handle_path_from_dos_path
*
* Purpose:
* Converts a DOS-style path string into the Client32-compatible
* NWHandlePathStruct used by the NCP87 wrappers.
*
* Notes:
* Drive prefixes, leading slashes and simple current-directory components
* are skipped so tool callers can pass ordinary DOS paths.
*/
static UI c32_build_handle_path_from_dos_path(uint8 *buf, uint8 dhandle,
uint16 dirbase, uint8 style,
const char *dospath)
@@ -226,6 +297,20 @@ static UI c32_build_handle_path_from_dos_path(uint8 *buf, uint8 dhandle,
* shape. It is intentionally kept small and isolated here so FLAG and later
* tools do not carry the old exploratory tests.
*/
/*
* c32_get_ncp_handle
*
* Purpose:
* Resolves the active MARS/NetWare connection into the Client32 NCP handle
* used by the Raw5 requester probe.
*
* Requester path:
* C32_MapVar_Probe followed by C32_OpenRef_Probe.
*
* Returns:
* 0 on success. Non-zero values indicate that the connection reference or
* Client32 NCP handle could not be obtained.
*/
int c32_get_ncp_handle(uint16 *handle_lo, uint16 *handle_hi)
{
uint8 mapout[32];
@@ -266,6 +351,18 @@ int c32_get_ncp_handle(uint16 *handle_lo, uint16 *handle_hi)
}
/*
* c32_copy_open_reply_to_handle6
*
* Purpose:
* Extracts the six-byte server file handle from an NCP87/01 Open/Create
* reply fragment for later NCP74 Copy or NCP66 Close calls.
*
* Notes:
* The exact handle layout is still part of the NCOPY investigation. This
* helper keeps the extraction in one place so the code can be corrected
* without touching the callers.
*/
static void c32_copy_open_reply_to_handle6(C32_NWFILE_HANDLE6 *dst,
const uint8 *src)
{
@@ -285,6 +382,24 @@ static void c32_copy_open_reply_to_handle6(C32_NWFILE_HANDLE6 *dst,
memcpy(dst->h, src, 6);
}
/*
* ncp87_01_open_create_entry
*
* Purpose:
* Opens or creates a namespace file/directory entry and returns the server
* file handle required by copy/close style NCPs.
*
* NCP:
* Function 0x57 / subfunction 0x01, Open/Create File or Subdirectory.
*
* Requester path:
* Client32 Raw5 fragment request.
*
* Notes:
* This wrapper is currently experimental for NCOPY. Earlier tests showed
* that the old INT 21h F257 path reaches MARS-NWE but does not reliably
* return the open file handle to the DOS caller.
*/
int ncp87_01_open_create_entry(const char *path_name,
uint16 dir_handle,
uint8 open_create_mode,
@@ -385,6 +500,23 @@ int ncp87_01_open_create_entry(const char *path_name,
return(0);
}
/*
* ncp74_file_server_copy
*
* Purpose:
* Copies file data server-side between two already-open NetWare file
* handles.
*
* NCP:
* Function 0x4a, File Server Copy.
*
* Requester path:
* Direct F24A Net_Call wrapper.
*
* Notes:
* Offsets and byte count are encoded high-low. The source and destination
* handles must be the six-byte server handles accepted by the file server.
*/
int ncp74_file_server_copy(const C32_NWFILE_HANDLE6 *src,
const C32_NWFILE_HANDLE6 *dst,
uint32 src_offset,
@@ -432,6 +564,18 @@ int ncp74_file_server_copy(const C32_NWFILE_HANDLE6 *src,
return(0);
}
/*
* ncp66_close_file
*
* Purpose:
* Closes a NetWare server file handle returned by an open/create wrapper.
*
* NCP:
* Function 0x42 / decimal 66, Close File.
*
* Requester path:
* Direct F242 Net_Call wrapper.
*/
int ncp66_close_file(const C32_NWFILE_HANDLE6 *handle)
{
struct {
@@ -459,6 +603,20 @@ int ncp66_close_file(const C32_NWFILE_HANDLE6 *handle)
}
/*
* ncp87_06_obtain_rim_attributes
*
* Purpose:
* Reads only the DOS attribute field for a directory entry using the
* NCP87 return-information-mask mechanism.
*
* NCP:
* Function 0x57 / subfunction 0x06, Obtain File or Subdirectory
* Information, RIM_ATTRIBUTES.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_06_obtain_rim_attributes(const char *name,
uint16 dir_handle,
uint32 *attr_out,
@@ -532,6 +690,20 @@ int ncp87_06_obtain_rim_attributes(const char *name,
}
/*
* ncp87_06_obtain_ndir_info
*
* Purpose:
* Reads the DOS namespace information block used by NDIR for Novell-style
* metadata output.
*
* NCP:
* Function 0x57 / subfunction 0x06, Obtain File or Subdirectory
* Information, RIM_ALL.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_06_obtain_ndir_info(const char *path_name,
uint16 dir_handle,
C32_NDIR_INFO *info_out,
@@ -647,6 +819,19 @@ int ncp87_06_obtain_ndir_info(const char *path_name,
/*
* ncp87_07_modify_dos_info
*
* Purpose:
* Writes selected DOS namespace metadata fields for a file or directory.
*
* NCP:
* Function 0x57 / subfunction 0x07, Modify File or Subdirectory DOS
* Information.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_07_modify_dos_info(const char *name,
uint16 dir_handle,
uint32 change_mask,
@@ -755,6 +940,16 @@ int ncp87_07_modify_dos_info(const char *name,
return(0);
}
/*
* ncp87_07_modify_dos_attributes
*
* Purpose:
* Convenience wrapper around ncp87_07_modify_dos_info() for changing only
* the DOS attributes field.
*
* NCP:
* Function 0x57 / subfunction 0x07 with DM_ATTRIBUTES.
*/
int ncp87_07_modify_dos_attributes(char *name,
uint16 dir_handle,
uint32 attrs,
@@ -779,6 +974,18 @@ int ncp87_07_modify_dos_attributes(char *name,
}
/*
* ncp87_1d_get_effective_rights
*
* Purpose:
* Reads the effective rights mask for a path.
*
* NCP:
* Function 0x57 / subfunction 0x1d, Get Effective Rights.
*
* Requester path:
* Client32 Raw5 fragment request with an NWHandlePathStruct.
*/
int ncp87_1d_get_effective_rights(const char *path_name,
uint16 dir_handle,
uint16 *rights_out,
@@ -873,6 +1080,19 @@ int ncp87_1d_get_effective_rights(const char *path_name,
}
/*
* ncp87_1d_get_effective_rights_by_dirent
*
* Purpose:
* Reads effective rights using a volume number and DOS directory number
* instead of a textual path.
*
* NCP:
* Function 0x57 / subfunction 0x1d, Get Effective Rights.
*
* Notes:
* NDIR uses this form after obtaining directory-entry metadata.
*/
int ncp87_1d_get_effective_rights_by_dirent(uint8 vol_number,
uint32 dos_dir_number,
uint16 *rights_out,
@@ -963,6 +1183,17 @@ int ncp87_1d_get_effective_rights_by_dirent(uint8 vol_number,
/*
* c32_build_ncp22_trustee_path
*
* Purpose:
* Builds the volume-qualified path format required by old NCP22 trustee
* calls from the DOS utility display/header path.
*
* Notes:
* This helper intentionally strips the server component and leaves a
* SYS:DIR\FILE style path for directory handle 0 requests.
*/
static int c32_build_ncp22_trustee_path(char *out, const char *path_name, int max)
{
char header[300];
@@ -1000,6 +1231,19 @@ static int c32_build_ncp22_trustee_path(char *out, const char *path_name, int ma
return(0);
}
/*
* ncp22_27_set_trustee_rights
*
* Purpose:
* Adds or updates a trustee assignment using the old directory services NCP
* fallback path.
*
* NCP:
* Function 0x16 / subfunction 0x27, Add Extended Trustee.
*
* Requester path:
* E200 Net_Call wrapper with a volume-qualified path.
*/
int ncp22_27_set_trustee_rights(const char *path_name,
uint16 dir_handle,
uint32 object_id,
@@ -1047,6 +1291,19 @@ int ncp22_27_set_trustee_rights(const char *path_name,
}
/*
* ncp22_2b_delete_trustee_rights
*
* Purpose:
* Deletes a trustee assignment using the old directory services NCP
* fallback path.
*
* NCP:
* Function 0x16 / subfunction 0x2b, Delete Trustee.
*
* Requester path:
* E200 Net_Call wrapper with a volume-qualified path.
*/
int ncp22_2b_delete_trustee_rights(const char *path_name,
uint16 dir_handle,
uint32 object_id)
@@ -1092,6 +1349,18 @@ int ncp22_2b_delete_trustee_rights(const char *path_name,
return(0);
}
/*
* ncp87_0a_add_trustee_rights
*
* Purpose:
* Adds trustee rights using the namespace-aware NCP87 trustee API.
*
* NCP:
* Function 0x57 / subfunction 0x0a, Add Trustee Set.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_0a_add_trustee_rights(const char *path_name,
uint16 dir_handle,
uint32 object_id,
@@ -1199,6 +1468,19 @@ int ncp87_0a_add_trustee_rights(const char *path_name,
/*
* ncp87_05_find_trustee_rights
*
* Purpose:
* Scans trustee entries for a path until the requested bindery object id is
* found.
*
* NCP:
* Function 0x57 / subfunction 0x05, Scan Trustee Set.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_05_find_trustee_rights(const char *path_name,
uint16 dir_handle,
uint32 object_id,
@@ -1299,6 +1581,18 @@ int ncp87_05_find_trustee_rights(const char *path_name,
return(0xff); /* no trustee found / no more entries */
}
/*
* ncp87_0b_delete_trustee_rights
*
* Purpose:
* Deletes trustee rights using the namespace-aware NCP87 trustee API.
*
* NCP:
* Function 0x57 / subfunction 0x0b, Delete Trustee Set.
*
* Requester path:
* Client32 Raw5 fragment request.
*/
int ncp87_0b_delete_trustee_rights(const char *path_name,
uint16 dir_handle,
uint32 object_id,