BPQ Home   BPQ32 Home

BPQ32 Application Programming Interface.

Introduction.

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 application programs. 

History.

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 BPQHOST.TXT 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 Win32.

Implementation

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 BPQCTRL.OCX . 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.

The program is a mixture of Assembler and C, and was developed using Microsoft Visual C++ Version 4.

API Overview.

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 switch.

A program must allocate a number of streams at startup in order to receive incoming calls. Normally it calls FindFreeStream - it is possible to allocate a particular stream using AllocateStream , but this requires careful coordination between applications, to make sure two don't try to use the same stream. It then calls SetAPPL 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 (using DeallocateStream ) before the program terminates.

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.

API Interface.

System Functions.

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 13.

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)

Release 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 7 (part)).

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 7 (part)).

int APIENTRY GetCallsign(int stream, LPSTR callsign)

Returns call connected on stream (BPQHOST function 8 (part)).

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 function 1) 
Top bit of flags enables monitoring

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 GetConnectionInfo 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 count )

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
14/11/2006