/*++
Copyright (c) 1991-1993 Microsoft Corporation
Module Name:
NetLib.h
Abstract:
This header file declares various common routines for use in the
networking code.
Author:
John Rogers (JohnRo) 14-Mar-1991
Environment:
Portable to any flat, 32-bit environment. (Uses Win32 typedefs.)
Requires ANSI C extensions: slash-slash comments, long external names.
Notes:
You must include <windows.h> and <lmcons.h> before this file.
Revision History:
14-Mar-1991 JohnRo
Created.
20-Mar-1991 JohnRo
Moved NetpPackString here (was NetapipPackString). Removed tabs.
21-Mar-1991 RitaW
Added NetpCopyStringToBuffer.
02-Apr-1991 JohnRo
Moved NetpRdrFsControlTree to <netlibnt.h>.
03-Apr-1991 JohnRo
Fixed types for NetpCopyStringToBuffer.
08-Apr-1991 CliffV
Added NetpCopyDataToBuffer
10-Apr-1991 JohnRo
Added NetpSetParmError (descended from CliffV's SetParmError).
10-Apr-1991 Danl
Added NetpGetComputerName
24-Apr-1991 JohnRo
Avoid conflicts with MIDL-generated files.
Added NetpAdjustPreferedMaximum().
NetpCopyStringToBuffer's input string ptr is optional.
26-Apr-1991 CliffV
Added NetpAllocateEnumBuffer.
Added typedefs PTRDIFF_T and BUFFER_DESCRIPTOR.
16-Apr-1991 JohnRo
Clarify UNICODE handling of pack and copy routines.
24-Jul-1991 JohnRo
Provide NetpIsServiceStarted() for use by <netrpc.h> macros.
29-Oct-1991 JohnRo
Added NetpChangeNullCharToNullPtr() macro.
29-Oct-1991 Danhi
Add function prototypes for DosxxxMessage Api's
20-Nov-1991 JohnRo
Removed NT dependencies to reduce recompiles.
09-Jan-1992 JohnRo
Added NetpGetDomainName().
23-Jan-1992 JohnRo
Added IN_RANGE() macro based on MadanA's RANGECHECK().
25-Mar-1992 RitaW
Added SET_SERVICE_EXITCODE() macro for setting Win32 vs
service specific exitcode.
06-May-1992 JohnRo
Added NetpGetLocalDomainId() for PortUAS.
Added NetpTranslateServiceName() for service controller APIs.
27-Jul-1992 Madana
Added NetpWriteEventlog function proto type.
05-Aug-1992 JohnRo
RAID 3021: NetService APIs don't always translate svc names.
09-Sep-1992 JohnRo
RAID 1090: net start/stop "" causes assertion.
14-Oct-1992 JohnRo
RAID 9020: setup: PortUas fails ("prompt on conflicts" version).
02-Nov-1992 JohnRo
Added NetpIsRemoteServiceStarted().
15-Feb-1993 JohnRo
RAID 10685: user name not in repl event log.
24-Mar-1993 JohnRo
Repl svc shuold use DBFlag in registry.
--*/
#ifndef _NETLIB_
#define _NETLIB_
// These must be included first:
// (none, because of MIDL conflicts.)
// #include <windows.h> // IN, LPBYTE, LPVOID, NULL, etc.
// #include <lmcons.h> // NET_API_STATUS, etc.
// These may be included in any order:
#include <string.h> // memcpy().
#ifdef CDEBUG // Debug in ANSI C environment?
#include <netdebug.h> // NetpAssert().
#endif // ndef CDEBUG
// Arbitrary. PortUAS has at least 16 args in one message.
// This allows arg numbers 1-19 to be used.
// (This is used by NetpFindNumberedFormatInWStr() and its caller(s).
#define MAX_NETLIB_MESSAGE_ARG 19
//
// IN_RANGE(): Make sure SomeValue is between SomeMin and SomeMax.
// Beware side-effects (SomeValue is evaluated twice).
// Created by JohnRo from MadanA's RANGECHECK().
//
// BOOL
// IN_RANGE(
// IN DWORD SomeValue,
// IN DWORD SomeMin,
// IN DWORD SomeMax
// );
//
#define IN_RANGE(SomeValue, SomeMin, SomeMax) \
( ((SomeValue) >= (SomeMin)) && ((SomeValue) <= (SomeMax)) )
//
// SET_SERVICE_EXITCODE() sets the SomeApiStatus to NetCodeVariable
// if it is within the NERR_BASE and NERR_MAX range. Otherwise,
// Win32CodeVariable is set. This original code came from JohnRo.
//
#define SET_SERVICE_EXITCODE(SomeApiStatus, Win32CodeVariable, NetCodeVariable) \
{ \
if ((SomeApiStatus) == NERR_Success) { \
(Win32CodeVariable) = NO_ERROR; \
(NetCodeVariable) = NERR_Success; \
} else if (! IN_RANGE((SomeApiStatus), MIN_LANMAN_MESSAGE_ID, MAX_LANMAN_MESSAGE_ID)) { \
(Win32CodeVariable) = (DWORD) (SomeApiStatus); \
(NetCodeVariable) = (DWORD) (SomeApiStatus); \
} else { \
(Win32CodeVariable) = ERROR_SERVICE_SPECIFIC_ERROR; \
(NetCodeVariable) = (DWORD) (SomeApiStatus); \
} \
}
VOID
NetpAdjustPreferedMaximum (
IN DWORD PreferedMaximum,
IN DWORD EntrySize,
IN DWORD Overhead,
OUT LPDWORD BytesToAllocate OPTIONAL,
OUT LPDWORD EntriesToAllocate OPTIONAL
);
DWORD
NetpAtoX(
IN LPCWSTR String
);
// VOID
// NetpChangeNullCharToNullPtr(
// IN OUT LPTSTR p
// );
//
#define NetpChangeNullCharToNullPtr(p) \
{ \
if ( ((p) != NULL) && (*(p) == '\0') ) { \
(p) = NULL; \
} \
}
// Portable memory move/copy routine: This is intended to have exactly
// the semantics of ANSI C's memcpy() routine, except that the byte count
// is 32 bits long.
//
// VOID
// NetpMoveMemory(
// OUT LPBYTE Dest, // Destination (must not be NULL).
// IN LPBYTE Src, // Source
// IN DWORD Size // Byte count
// );
#ifdef CDEBUG
// Note that C6 version doesn't allow 32-bit Size, hence the
// assertion. Replace this macro with another if this is a problem.
#define NetpMoveMemory(Dest,Src,Size) \
{ \
NetpAssert( (Size) == (DWORD) (size_t) (Size)); \
(void) memcpy( (Dest), (Src), (size_t) (Size) ); \
}
#else // ndef CDEBUG
#define NetpMoveMemory(Dest,Src,Size) \
(void) memcpy( (Dest), (Src), (size_t) (Size) )
#endif // ndef CDEBUG
DWORD
NetpPackString(
IN OUT LPTSTR * string, // pointer by reference: string to be copied.
IN LPBYTE dataend, // pointer to end of fixed size data.
IN OUT LPTSTR * laststring // pointer by reference: top of string data.
);
//
// This routine is like NetpPackString, except that it does not expect the
// caller to assign the pointer of the source string to the variable in the
// fixed size structure before the call. It also takes a string character
// count parameter instead of calling strlen on String.
//
BOOL
NetpCopyStringToBuffer (
IN LPTSTR String OPTIONAL,
IN DWORD CharacterCount,
IN LPBYTE FixedDataEnd,
IN OUT LPTSTR *EndOfVariableData,
OUT LPTSTR *VariableDataPointer
);
//
// This routine is like NetpCopyStringToBuffer except it copies any data
// (not just strings), it does not put a zero byte at the end of the
// data, and it allows the alignment of the resultant copied data to be
// specified.
//
BOOL
NetpCopyDataToBuffer (
IN LPBYTE Data,
IN DWORD ByteCount,
IN LPBYTE FixedDataEnd,
IN OUT LPBYTE *EndOfVariableData,
OUT LPBYTE *VariableDataPointer,
IN DWORD Alignment
);
//
// Declare a type for the difference between two pointers.
//
// This must be at least as long as a ptrdiff_t but we don't want to
// add a dependency on <stddef.h> here.
//
typedef DWORD PTRDIFF_T;
//
// Declare a description of an enumeration buffer.
//
typedef struct _BUFFER_DESCRIPTOR {
LPBYTE Buffer; // Pointer to the allocated buffer.
DWORD AllocSize; // Current size of the allocated buffer.
DWORD AllocIncrement; // Amount to increment size by on each reallocate.
LPBYTE EndOfVariableData;// Pointer past last avaliable byte of string space
LPBYTE FixedDataEnd; // Pointer past last used byte of fixed data space
} BUFFER_DESCRIPTOR, *PBUFFER_DESCRIPTOR;
//
// This routine handles all the details of allocating and growing a
// buffer returned from an enumeration function. It takes the users
// prefered maximum size into consideration.
//
#define NETP_ENUM_GUESS 16384 // Initial guess for enumeration buffer size
NET_API_STATUS
NetpAllocateEnumBuffer(
IN OUT PBUFFER_DESCRIPTOR BufferDescriptor,
// Caller must deallocate BD->Buffer using MIDL_user_free.
IN BOOL IsGet,
IN DWORD PrefMaxSize,
IN DWORD NeededSize,
IN VOID (*RelocationRoutine)( IN DWORD RelocationParameter,
IN OUT PBUFFER_DESCRIPTOR BufferDescriptor,
IN PTRDIFF_T Offset ),
IN DWORD RelocationParameter
);
// VOID
// NetpBuildASCIIZ(
// OUT LPSTR Dest, // Destination (will be null terminated).
// IN LPBYTE Src, // Source (not null terminated).
// IN DWORD Count // Byte count (not including null char).
// );
#define NetpBuildASCIIZ(dest,src,count) \
{ \
NetpMoveMemory( (dest), (src), (count) ); \
*( ((LPBYTE)(dest)) + (count) ) = '\0'; \
}
// Convert C runtime errno value to windows/lanman API status value.
NET_API_STATUS
NetpErrNoToApiStatus(
IN int Err
);
BOOL
NetpIsRemoteServiceStarted(
IN LPTSTR UncServerName OPTIONAL,
IN LPTSTR ServiceName
);
BOOL
NetpIsServiceStarted(
IN LPTSTR ServiceName
);
//
// Portable memory allocation routines. Memory is per-process only.
//
// Allocate memory, or return NULL if not available.
LPVOID
NetpMemoryAllocate(
IN DWORD Size
);
// Free memory at Address (must have been gotten from NetpMemoryAllocate or
// NetpMemoryReallocate). (Address may be NULL.)
VOID
NetpMemoryFree(
IN LPVOID Address OPTIONAL
);
// Reallocate block (now at OldAddress) to NewSize. OldAddress may be NULL.
// Contents of block are copied if necessary. Returns NULL if unable to
// allocate additional storage.
LPVOID
NetpMemoryReallocate(
IN LPVOID OldAddress OPTIONAL,
IN DWORD NewSize
);
//
// Random handy macros:
//
#define NetpPointerPlusSomeBytes(p,n) \
(LPBYTE) ( ( (LPBYTE) (p)) + (n) )
#define NetpSetOptionalArg(arg, value) \
{ \
if ((arg) != NULL) { \
*(arg) = (value); \
} \
}
//
// Set the optional ParmError parameter
//
#define NetpSetParmError( _ParmNumValue ) \
if ( ParmError != NULL ) { \
*ParmError = (_ParmNumValue); \
}
#if defined(lint) || defined(_lint)
#define UNUSED(x) { (x) = (x); }
#else
#define UNUSED(x) { (void) (x); }
#endif
//
// NetpGetComputerName retrieves the local computername from the local
// configuration database.
//
NET_API_STATUS
NetpGetComputerName (
IN LPTSTR *ComputerNamePtr);
// Note: calls to NetpGetDomainId should eventually be replaced by calls
// to NetpGetLocalDomainId. --JR
NET_API_STATUS
NetpGetDomainId (
OUT PSID *RetDomainId // alloc and set ptr (free with LocalFree)
);
NET_API_STATUS
NetpGetDomainName (
IN LPTSTR *DomainNamePtr // alloc and set ptr (free with NetApiBufferFree)
);
typedef enum _LOCAL_DOMAIN_TYPE {
LOCAL_DOMAIN_TYPE_ACCOUNTS,
LOCAL_DOMAIN_TYPE_BUILTIN,
LOCAL_DOMAIN_TYPE_PRIMARY
} LOCAL_DOMAIN_TYPE, *PLOCAL_DOMAIN_TYPE, *LPLOCAL_DOMAIN_TYPE;
NET_API_STATUS
NetpGetLocalDomainId (
IN LOCAL_DOMAIN_TYPE TypeWanted,
OUT PSID *RetDomainId // alloc and set ptr (free with LocalFree)
);
//
// Get SID for this thread. (Caller must impersonate if they want client's
// SID.)
//
NET_API_STATUS
NetpGetUserSid(
OUT PSID *UserSid // alloc and set ptr (free with LocalFree).
);
//
// NetService API helpers
//
// BOOL
// NetpIsServiceLevelValid(
// IN DWORD Level
// );
//
#define NetpIsServiceLevelValid( Level ) \
( ((Level)==0) || ((Level)==1) || ((Level)==2) )
BOOL
NetpIsServiceNameValid(
IN LPTSTR ServiceName,
IN BOOL UseDownlevelRules
);
NET_API_STATUS
NetpTranslateNamesInServiceArray(
IN DWORD Level,
IN LPVOID ArrayBase,
IN DWORD EntryCount,
IN BOOL PreferNewStyle,
OUT LPVOID * NewArrayBase
);
NET_API_STATUS
NetpTranslateServiceName(
IN LPTSTR GivenServiceName,
IN BOOL PreferNewStyle,
OUT LPTSTR * TranslatedName
);
//
// Mapping routines to map DosxxxMessage API's to FormatMessage
//
WORD
DosGetMessageW(
IN LPTSTR * InsertionStrings,
IN WORD NumberofStrings,
OUT LPTSTR Buffer,
IN WORD BufferLength,
IN WORD MessageId,
IN LPTSTR FileName,
OUT PWORD pMessageLength
);
WORD
DosInsMessageW(
IN LPTSTR * InsertionStrings,
IN WORD NumberofStrings,
IN OUT LPTSTR InputMessage,
IN WORD InputMessageLength,
OUT LPTSTR Buffer,
IN WORD BufferLength,
OUT PWORD pMessageLength
);
WORD
DosPutMessageW(
unsigned int hf,
WORD us,
PTCHAR pch);
DWORD
NetpGetPrivilege(
IN DWORD numPrivileges,
IN PULONG pulPrivileges
);
DWORD
NetpReleasePrivilege(
VOID
);
DWORD
NetpWriteEventlog(
LPWSTR Source,
DWORD EventID,
DWORD EventType,
DWORD NumStrings,
LPWSTR *Strings,
DWORD DataLength,
LPVOID Data
);
#endif // ndef _NETLIB_
