DOCERR: Important Information on RPC 2.0 Missing from the Docs

• Microsoft Windows Software Development Kit (SDK) for Windows for Workgroups version 3.11
• Microsoft Win32 Software Development Kit (SDK) for Windows NT version 3.5

SUMMARY

This article contains important information not included in the Microsoft RPC programming documentation or in Help about Microsoft RPC version 2.0. This information is identical to the information provided in the RPCREAD.ME file in the Win32 SDK (MSTOOLS\SAMPLES\RPC\) for Windows NT version 3.5.

Microsoft RPC is a toolkit for developing distributed applications in C/C++. The toolkit includes:

• MIDL compiler for Microsoft Windows NT.
• C/C++ language header files and run-time libraries for Windows NT, Microsoft Windows versions 3.x, and MS-DOS.
• Sample programs for Windows NT, Windows versions 3.x, and MS-DOS.

MORE INFORMATION

This article is organized into the following sections:

• Installation
• Documentation
• Before Using RPC
• MIDL Issues
• Run-Time API Issues

Installation

The Windows NT SDK provides the components of the RPC toolkit as part of its standard installation. No additional installation is required. To produce MS-DOS and Windows 3.x RPC clients, install version 1.50 of the Microsoft Visual C/C++ development environment, and then install the MS- DOS/Win16 RPC tookit from disk. To install the MS-DOS/Windows 3.x version of the RPC toolkit, use the Setup program in the MSTOOLS\RPC_DOS\DISK1 directory.

Because the 16-bit MIDL compiler is no longer supported, you must develop applications using the 32-bit MIDL compiler. However, to write MS-DOS or Windows 3.x applications without a 32-bit C/C++ compiler capable of targeting MS-DOS, you must compile the IDL file with a 32-bit MIDL compiler on Windows NT. Then, compile the application and stubs using your C/C++ compiler. To write MS-DOS or Windows 3.x applications using a 32-bit C/C++ compiler that is capable of targeting MS-DOS, compile both the IDL file and C/C++ files on Windows NT.

Documentation

The RPC Programmer's Guide and Reference is available in Help and includes conceptual material, MIDL language and command-line references, and run-time API references.

Because many new features have been included in this version of Microsoft RPC, see the New in this Version of RPC help topic.

RPC sample program source files are available in the directory MSTOOLS\SAMPLES\RPC. The MSTOOLS\SAMPLES\RPC\README.TXT file describes each sample.

Before Using RPC

Read the following section on MIDL and run-time API issues before attempting to use this version of RPC. These sections contain important information that is not documented in Help.

MIDL Issues

The 16-bit MIDL compiler for MS-DOS or Windows 3.x is no longer supported. Use the 32-bit MIDL compiler switch /env with either the DOS or WIN16 option.

Note the following when using this version of the MIDL compiler:

• When compiling the generated stubs, warnings about different levels of pointer indirection or different const specifications are benign.
• When using the DOS or WIN option of the -env switch, the compiler will not set the correct packing level to 2. In this case, you must explicitly specify the correct packing level by using the /Zp or /pack switch.
• For Alpha platforms, procedure serialization stubs must be compiled on the C compiler by using the -Od switch. The procedure encoding/decoding stubs on the Alpha platform should not be compiled as optimized (for example, using the -Ox switch). This affects the stubs on the Alpha platform only if the serializing procedure uses one of the following attributes on top-level parameters:

      - array or ptr attributes, such as size_is or length_is.
      - The switch_is union attribute.
  

• A structure whose only member is a conformant string results in an MIDL compiler assert.
• In the osf mode of the compiler, the default allocate and free routines map to NdrRpcSmClientAllocate and NdrRpcSmClientFree. The signatures for these routines are in RPCNDR.H

Run-Time API Issues

When using the ncacn_spx and ncadg_ipx transports, the server name is exactly the same as the Windows NT server name. However, because the names are distributed using Novell protocols, they must conform to the Novell naming conventions. If a server name is not a valid Novell name, servers will not be able to create endpoints with the ncacn_spx or ncadg_ipx transports. The following is a partial list of characters prohibited in Novell server names:

   "  *  +  .  /  :  ;  <  =  >  ?  [  ]  \  |

The ncacn_spx transport is not supported by the version of NWLink supplied with MS Client 3.0; however, ncadg_ipx is supported.

Backslashes are now optional in the host name for ncacn_np, for consistency with the other transports.

The datagram protocols (ncadg_ipx, ncadg_ip_udp) have the following limitations:

• They do not support callbacks. Any functions using the callback attribute will fail.
• They do not support the RPC security API (RpcBindingSetAuthInfo, RpcImpersonateClient, and so on).

• RpcCancelThread will alert the specified thread, but will not interrupt a pending RPC.
• RpcTestCancel will return RPC_S_OK if the current thread has been alerted.
• RpcMgmtSetCancelTimeout has no visible effect.

The function RpcBindingSetAuthInfo does not accept the value RPC_C_AUTHN_DEFAULT.

To use the RpcBindingSetAuthInfo routine and, in particular, when using MS-DOS authentication in this version of RPC, note this information:

• The constant RPC_C_AUTHN_WINNT has been defined in the header RPCDCE.H. This constant should be passed as the AuthnSvc parameter to use the Windows NT LAN Manager Security Support Provider (NTLMSSP) service.
• When using the RPC_C_AUTHN_WINNT authentication service, the AuthIdentity parameter should be a pointer to a SEC_WINNT_AUTH_IDENTITY structure, defined in RPCDCE.H. This structure contains strings for the user's domain, username, and password. You can pass a NULL pointer to use the information for the currently logged-in user.

When using authenticated RPC on a system composed of Novell NetWare and Windows version 3.x (not Windows for Workgroups), you must run the optional NETBIOS.EXE program before starting Windows.

The 16-bit SDK cannot be installed on a Windows NT computer unless the current user is an administrator.

Supported Platforms for Runtime APIs

The following function is supported only by 16-bit Windows 3.x platforms:

RpcWinSetYieldInfo

The following functions are supported only by 32-bit Windows NT platforms:

DceErrorInqTest RpcBindingInqAuthClient RpcBindingServerFromClient RpcCancelThread RpcEpRegister RpcEpUnregister RpcIfIdVectorFree RpcImpersonateClient RpcNetworkInqProtseqs RpcObjectInqType RpcObjectSetInqFn RpcObjectSetType RpcProtseqVectorFree RpcRevertToSelf RpcServerInqBindings RpcServerInqIf RpcServerListen RpcServerRegisterAuthInfo RpcServerRegisterIf RpcServerUnregisterIf RpcServerUse*Protseq* RpcMgmtInqIfIds RpcMgmtInqStats RpcMgmtIsServerListening RpcMgmtInqServerPrincName RpcMgmtSetAuthorizationFn RpcMgmtSetCancelTimeout RpcMgmtSetServerStackSize RpcMgmtStatsVectorFree RpcMgmtStopServerListening RpcMgmtWaitServerListen RpcMgmtEnableIdleCleanup RpcMgmtEpElt* RpcMgmtEpUnregister RpcNsBindingExport RpcNsBindingUnexport RpcTestCancel

All other runtime functions are supported on Windows NT, Windows 3.x, and MS-DOS platforms.

REFERENCES

RPCREAD.ME in \MSTOOLS\SAMPLES\RPC in Win32SDK for Windows NT 3.5 on MSDN.