NSPR: Windows 3.1 special cases
[Contents] [Previous]
[Next] [Last]
Appendix B:
Windows 3.1 Special Cases
This chapter describes platform specific features supporting Windows 3.1
[Note: The term Win16 is used interchangeable with Windows 3.1 or Windows
3.11 for Workgroups.] This chapter is specific to Win16 and does not apply
to other platforms supported for NSPR.
Handling stdio for command line applications.
Win16 provides an API for writing in a Windowed environment. That API should
be used when developing a GUI application. A command line or console application
requires a different approach. On Win16, a command line application is
actually run in a Windowed environment. The environment intercepts printf()
and similar functions and displays the output in a wrapper window. The
Microsoft C compiler, Version 1.52, calls this environment QuickWin. NSPR
2.0 for Win16 was developed using the Watcom C/C++ Compiler, Version 11.0a;
this compiler provides a similar environment.
When a command line application uses the printf() library call, all
is well. The output is displayed in the wrapper (QuickWin) window. If the
application uses PR_Printf(), then the call is to the NSPR .DLL. In
the .DLL environment, NSPR does not have ready access to the wrapper window
that is directly available to the application program (the .EXE). To get
text displayed in the wrapper window, NSPR provides a module (w16stdio.c)
to be linked with the application program's .EXE file. By linking the command
line application with the w16stdio.obj file, messages written using NSPR's
"printf" interfaces will be displayed in the wrapper window.
PR_STDIO_INIT
Initialize NSPR to write to stdio in command line applications.
Syntax
#include <prwin16.h>
void PR_STDIO_INIT( void );
Parameter
void
Returns
void
Description
PR_STDIO_INIT() is a macro that registers the functions provided in w16stdio.c
with the NSPR .DLL. Thereafter, calls to PR_Printf() and related functions
will cause stdio output to be displayed in the wrapper window. PR_STDIO_INIT()
should be called in the command line application before any calls that
would try to write to stdio.
PR_STDIO_INIT() should not be called from GUI applications.
PR_STDIO_INIT() evaluates to a No-Operation on platforms other than
Win16.
Callback functions for applications using
NSPR
Win16 provides separate heap spaces for each executable (.EXE) and load
library (.DLL). Should a load library acquire storage on behalf of an executable,
when the executable subsequently frees that storage, heap corruption may
occur. To circumvent this, NSPR provides linkages and wrapper functions
so that some functions that acquire storage on behalf of the executable
can be called consistently from the environment of the executable.
Callback Method Registration Structure
PRMethodCallbackStr
The PRMethodCallbackStr structure contains a list of address of functions
to be called from the NSPR executable. These functions are provided (optionally)
by NSPR in module w16callb.c. The module w16callb.c should be statically
linked with the user application executable.
Callback Functions
PR_INIT_CALLBACKS
Register NSPR provided call back functions.
Syntax
#include <prwin16.h>
void PR_INIT_CALLBACKS( void );
Parameter
void
Returns
void
Description
Registers a set of NSPR provided callback functions for the defined set
of functions to be executed in the application's .EXE environment.
_PL_W16CallBackMalloc
Wrap a call to malloc().
Syntax
#include <prwin16.h>
void *_PL_W16CallBackMalloc(size_t size);
Parameter
| size
|
Size argument to be passed to malloc(). |
Returns
Pointer to storage of size size or NULL.
Description
Call malloc().
_PL_W16CallBackCalloc
Wrap a call to calloc().
Syntax
#include <prwin16.h>
void *_PL_W16CallBackCalloc(size_t n, size_t size);
Parameter
| n
|
number of objects argument to be passed
to calloc(). |
|
size
|
Size argument to be passed to calloc() |
Returns
Pointer to storage of size ( n * size ) or NULL.
Description
Call calloc().
_PL_W16CallBackRealloc
Wrap a call to realloc().
Syntax
#include <prwin16.h>
void *_PL_W16CallBackRealloc(void *old_blk, size_t size);
Parameter
| old_blk
|
Pointer to old block of storage passed
to realloc(). |
|
size
|
Size argument to be passed to realloc(). |
Returns
Pointer to new storage or NULL.
Description
Call realloc().
_PL_W16CallBackFree
Wrap a call to free().
Syntax
#include <prwin16.h>
void _PL_W16CallBackFree(void *ptr);
Parameter
| ptr
|
Pointer to be passed to free(). |
Returns
void
Description
Call free().
_PL_W16CallBackGetenv
Wrap a call to getenv().
Syntax
#include <prwin16.h>
void *_PL_W16CallBackGetenv(const char *name);
Parameter
| name
|
argument to be passed to getenv(). |
Returns
Pointer to environment variable referenced by name or NULL.
Description
Call getenv().
_PL_W16CallBackPutenv
Wrap a call to putenv().
Syntax
#include <prwin16.h>
PRIntn _PL_W16CallBackPutenv(const char *assoc);
Parameter
| assoc
|
Argument to putenv(). |
Returns
zero if successful, else -1.
Description
Call putenv().
_PL_W16CallBackStrftime
Wrap a call to strftime().
Syntax
#include <prwin16.h>
PRSize _PL_W16CallBackStrftime(
char *s,
size_t len,
const char *fmt,
const struct tm *p);
Parameter
| s
|
Output string. |
|
len
|
size of string s. |
|
fmt
|
format string |
|
p
|
pointer to struct tm |
All arguments are passed to strftime().
Returns
The return value from the call to strftime().
Description
Call strftime().
C++ Exception Context
GUI applications written using Microsoft's MFC library have to deal with
exceptions thrown by the runtime environment. These exceptions are specific
to a thread. The application's exception context must be associated with
the NSPR thread on which the exception occurs and must be handled. To associate
the exception context and to restore it across thread switches, NSPR
provides the following functions.
PR_W16SetExceptionContext
Set the exception context for a Win16 MFC application thread.
Syntax
#include <prwin16.h>
void PR_W16SetExceptionContext(void *context);
Parameter
An MFC exception context.
Returns
void
Description
The function preserves the exception context argument and associates it
with the current thread.
PR_W16GetExceptionContext
Get the exception context for a Win16 MFC application thread.
Syntax
#include <prwin16.h>
void *PR_W16SetExceptionContext(void);
Parameter
Returns
An exception context or a null pointer.
Description
The exception context previously set by PR_W16SetExceptionContext() for
the current thread.
The API defined for Windows 3.1 is specific to that platform.
[Contents] [Previous]
[Next] [Last]
Last Updated: Thu Dec 17 16:48:30 PST 1998
Copyright © 1998 Netscape
Communications Corporation
|
