BPQ Home  BPQ32 Home
BPQ32 Application Programming Interface.
BPQ32 is an AX.25 and NETROM protocol packet switching system for
use in Radio Amateur Packet Networks. The software provides similar functionality to
the DOS program BPQCODE.EXE. The switch can run on it's own, as
a stand-alone switch, but is more likely to be used to support one or
more application programs, such as a Packet BBS, DX Cluster or Chat
Server. This document defines the interface provided by BPQ32 to such
BPQ32 is a port of the 16bit DOS program
BPQCODE.EXE to the Win32 environment. Win32 programs are likely to be written
in a high level language, such as "C" or Visual Basic, rather than the Assembler
usually used with DOS. The DOS API expects most parameters in CPU
Registers, which is inconvenient in high level languages, especially Visual
Basic. So BPQ32.DLL uses pointers to integers for these parameters. Most Windows API calls map more or less directly
onto the corresponding DOS API functions - see
for full details of the DOS
BPQHost API. BPQ32 also supports this interface, with 32 bit registers replacing
the 16 bit registers used in the DOS version, but this interface is most
likely to be of use when porting old 16 bit apps to
BPQ32 is implemented as a shared data DLL.
Applications are either linked to the DLL, so that the DLL is loaded as part of
the application, explicitly load the DLL using the Win32 LoadLibrary
function, or use the interface provided by the OLE (Active-X) control
. Normally the switch is loaded and
initialised when the first application connects to it, and remains running until
the last application closes. Subsequent applications connect to the same copy of
the switch. For this to work properly, all applications must load BPQ32.DLL from
the same directory. If you want the switch to remain running while your
application is closed and restated, then you can run BPQ32.exe first. This is a
dummy program, who's sole funtion is to hold bpq32.dll in memory.
program is a mixture of Assembler and C, and was developed using Microsoft
Visual C++ Version 4.
This document applies to BPQ32.DLL, Version 4.09v.
The BPQ32 switch supports up to 64 simultaneous
connections, called streams in the following text. The application program
(called program from now on, to avoid confusion with the Application definitions
within the switch) interacts with the switch over these streams, and the switch
manages connections with other stations in the network. For normal
communication, the program need not be aware of the physical network
configuration. However, the API does provide a way of sending packets such as
Beacons to individual radio ports.
The switch does not limit the number
of programs that may use it, but only supports 8 that may be connected
to by outside users. Each of these 8 applications may be given their own
callsign and alias, and may be advertised over the NETROM network. If they do
not have their own calls, users access them by connection to the switch, then
sending an appropriate command to the
A program must allocate a number of streams at
startup in order to receive incoming calls. Normally it calls
- it is possible to allocate a particular stream
, but this requires careful coordination
between applications, to make sure two don't try to use the same stream. It then
to define which of the 8 Applications it is
supporting. The program may also pre-allocate streams for outgoing connects, or
may allocate and deallocate them as required. All streams should be released
) before the program
The program may poll the switch for connections,
disconnections and messages, but normally it is better to get the switch to post
notifications to the application Window. This is done by using BPQSetHandle
to associate a stream with a Window Handle.
int APIENTRY GetFreeBuffs()
Returns number of free buffers (BPQHOST function 7 (part))
UCHAR * APIENTRY GetBPQDirectory();
Returns pointer to path of BPQDirectory. This is the
directory from which bpq32.dll loaded its configuration file (bpqcfg.bin).
Applications may wish to store their connfiguration information in the same place.
int APIENTRY GetAttachedProcesses();
Returns number of processes attached to BPQ32
int APIENTRY GetNumberofPorts()
Gets number of ports configured
int APIENTRY GetPortNumber(int portslot)
Gets port number (ports aren't necessarily numbered 1 to n).
int APIENTRY DecodeFrame(char * msg, char * buffer, int Stamp)
This is a utility to decode a received monitor frame into ascii text
int APIENTRY SetTraceOptions(long mask, int mtxparam, int mcomparam)
Sets the tracing options for DecodeFrame. Mask is a bit mask of ports
to monitor (ie 101 binary will monitor ports 1 and 3). MTX enables monitoring
of transmitted frames. MCOM enables monitoring of protocol control frames
(eg SABM, UA, RR), as well as info frames.
int APIENTRY WritetoConsole(char * buff)
Log a message to the bpq32 console.
Stream Related Functions.
int APIENTRY FindFreeStream()
Finds the first unused stream, and allocates it If none available,
returns 255, otherwise returns the stream number. See API function
BOOL APIENTRY GetAllocationState(int Stream);
Returns TRUE if stream is allocated
int APIENTRY AllocateStream(int stream)
Allocate stream. If stream is already allocated, return nonzero. Otherwise
allocate stream, and return zero.
int APIENTRY DeallocateStream(int stream)
int APIENTRY BPQSetHandle(int Stream, HWND hWnd)
Enable async operation.
The following values are returned in lParam of Windows Message
#define BPQMonitorAvail 1
#define BPQDataAvail 2
#define BPQStateChange 4
int APIENTRY RXCount(int Stream)
Returns count of packets waiting on stream (BPQHOST function
int APIENTRY TXCount(int Stream)
Returns number of packets on TX queue for stream (BPQHOST
function 7 (part)).
int APIENTRY MONCount(int Stream)
Returns number of monitor frames available (BPQHOST function
int APIENTRY GetCallsign(int stream, LPSTR callsign)
Returns call connected on stream (BPQHOST function 8
int APIENTRY GetConnectionInfo(int stream, char * callsign,
int * port, int * sesstype, int * paclen,
int * maxframe, int * l4window)
Returns connection info for stream (BPQHOST function 8).
int APIENTRY SessionControl(int stream, int command, int applmask)
Send Session Control command (BPQHOST function 6)
Command = 0 Connect using supplied APPL MASK
Command = 1 Connect
Command = 2 Disconect
Command = 3 Return to Node
int APIENTRY SetAppl(int stream, int flags, int mask)
Sets Application Mask and Flags for stream. (BPQHOST
Top bit of flags enables
Note that the Mask and Flags paramters are the opposite way round to the OLE Control.
This wasn't intended, but there are now too many programs around to correct it. So be careful!
int APIENTRY GetApplMask(int stream);
int APIENTRY GetApplFlags(int stream);
Return Application Mask or Flags for stream.
int APIENTRY SessionState(int stream, LPSTR state,LPSTR change)
Get current Session State. Any state changed is
ACK'ed automatically. See BPQHOST functions 4 and 5.
int APIENTRY SessionStateNoAck(int stream, int * state)
Get current Session State. Dont Ack state change. See BPQHOST function 4.
int APIENTRY SendMsg(int stream, LPSTR msg, int len)
Send message to stream (BPQHOST Function 2)
Note that messages will be transmitted 'on-air' as
sent by the application, ie the application is responsible for PACLEN. The
application may use
to determine what the node recommends, but this is not enforced.
The maximum length is 256 bytes, and frames larger than this will be ignored.
Normally length should be limited to 236, to avoid fragmentation when passed over a NETROM link.
int APIENTRY GetMsg(int stream, LPSTR msg, LPINT len, LPINT count )
Get message from stream. Returns length, and count of
frames still waiting to be collected. (BPQHOST function 3)
int APIENTRY GetMsgPerl(int stream, char * msg)
Perl Version - I couldn't get bpq32.pm to call GetMsg. Returns Length.
int APIENTRY GetRaw(int stream, LPSTR msg, LPINT len, LPINT
Get Raw (Trace) data (BPQHOST function 11)
int APIENTRY SendRaw(int port, LPSTR msg, int len)
Send Raw (KISS mode) frame to port (BPQHOST function 10)
Application Callsign Functions.
char * APIENTRY GetApplCall(int Appl)
char * APIENTRY GetApplAlias(int Appl)
long APIENTRY GetApplQual(int Appl)
BOOL APIENTRY SetApplCall(int Appl, char * NewCall)
BOOL APIENTRY SetApplAlias(int Appl, char * NewCall)
BOOL APIENTRY SetApplQual(int Appl, int NewQual)
Routines to support "Minimize to Tray"
All my BPQ related windows may be configured to minimise to a single Icon in the Notification Area. This helps to reduce clutter of the Task Bar. Other Applications may use the same system if they wish. See sample programs for details of how to use these routines.
BOOL APIENTRY GetMinimizetoTrayFlag()
int APIENTRY AddTrayMenuItem(HWND hWnd, char * Label)
int APIENTRY DeleteTrayMenuItem(HWND hWnd)
Visual Basic Definitions.
The following are Visual Basic (VB4) declarations for functions not available via bpqctrl.ocx
Private Declare Sub WritetoConsole Lib "bpq32.dll" _
Alias "_WritetoConsole@4" (ByVal Buffer As String)
Private Declare Function GetPortNumber Lib "bpq32.dll" _
Alias "_GetPortNumber@4" (ByVal portslot As Long) As Long
Private Declare Function ChangeSessionCallsign Lib "bpq32.dll" _
Alias "_ChangeSessionCallsign@8" (ByVal Stream As Long, ByVal AXCall As String) As Long
Private Declare Function GetMinimizetoTrayFlag Lib "bpq32.dll" _
Alias "_GetMinimizetoTrayFlag@0" () As Boolean
Private Declare Function AddTrayMenuItem Lib "bpq32.dll" _
Alias "_AddTrayMenuItem@8" (ByVal Handle As Long, ByVal Label As String) As Long
Private Declare Function DeleteTrayMenuItem Lib "bpq32.dll" _
Alias "_DeleteTrayMenuItem@4" (ByVal Handle As Long) As Long
John Wiseman G8BPQ