FAX drv table of contents

FAX C++ SDK Programmer Reference Guide

FAX C++ SDK USER'S GUIDE

The information contained in this manual is subject to change without notice. Changes, technical inaccuracies and typographical errors will be corrected in subsequent editions of this manual.

The software described in this manual is furnished under a license agreement. The software may be used or copied only in accordance with terms of the agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose other than the purchaser's own use without the express written consent of Black Ice Software, Inc.

20 Broad Street, Nashua, NH 03064

Release 12.XX

First Edition (December 1, 1994)

SP1055

ISBN 1-56275-009-8

Part Number: FAXCPP part 1 rev. 12212006

Printed in the USA

Table of Contents

Introduction................................................................................................................................. 3

Installing FAX C++....................................................................................................................... 5

FAX C++/ActiveX files...................................................................................................................................................... 10

Voice C++ files..................................................................................................................................................................... 12

Licensed Ports.................................................................................................................................................................... 13

Preparing Your Application for Shipping............................................................................................................. 14

Black Ice License/Protection files............................................................................................................................ 16

Using Fax C++............................................................................................................................... 17

How to Send a Fax.............................................................................................................................................................. 17

Hardware Detection........................................................................................................................................................ 18

How to send a Word, Excel, HTML, etc file as a fax.......................................................................................... 18

How To convert text into a fax.................................................................................................................................. 19

How To convert other image formats into a faxable TIFF............................................................................ 19

The FaxSpy utility............................................................................................................................................................... 19

How to close an application during faxing.......................................................................................................... 20

When to delete a Fax Object........................................................................................................................................ 20

How to Derive new class from the existing fax classes................................................................................ 21

How to convert a termination code to a string................................................................................................ 21

How to check the version of Fax C++...................................................................................................................... 21

How to check the number of Licensed Ports...................................................................................................... 21

How to create Fax C++ log files for modems..................................................................................................... 22

How to combine two or more image files into a multipage fax object.................................................... 22

Programming FAX C++................................................................................................................ 23

Architecture........................................................................................................................................................................ 23

FAX C++ Internal Architecture.................................................................................................................... 24

FAX C++ Data Flow (fig. 2.3).............................................................................................................................. 26

How To Start.............................................................................................................................................................. 27

The FAX C++ INI file format.............................................................................................................................. 27

Send and Receive FAX with C API................................................................................................................................ 30

Modem Settings........................................................................................................................................................ 30

Fax Manager................................................................................................................................................................ 30

Fax Manager and the User Application................................................................................................ 31

Fax Manager display modes.......................................................................................................................... 32

Page number messages..................................................................................................................................... 32

Which fax object is being sent on a given port.......................................................................... 33

Send FAX with C API................................................................................................................................................ 33

Receive FAX with C API......................................................................................................................................... 34

How to determine the port type.............................................................................................................. 35

Processing Fax C++ messages..................................................................................................................... 35

Error Handling......................................................................................................................................................... 36

Caller Number (CallerID) Detection...................................................................................................... 40

Color Fax - Send and Receive........................................................................................................................ 41

Polling - Remote document retrieval................................................................................................... 43

Polling - Sending document to remote station (Answer Mode)...................................... 43

Sending and receiving Multiple Documents..................................................................................... 45

Sending and receiving faxes using ECM (Error Correction Mode)............................... 47

Fax Class Interface............................................................................................................................................. 47

Managing Queues.................................................................................................................................................... 48

Working of the FaxC++ queue...................................................................................................................... 48

NT Services.................................................................................................................................................................. 49

Interfacing the Black Ice Print Drivers with Fax C++............................................................. 50

How to derive new Fax C++ classes....................................................................................................... 50

Standard or Fine Fax........................................................................................................................................... 54

Accessing the received page data real time................................................................................. 55

Adding new pages to a fax object during faxing....................................................................... 56

FAXCPP Global Data Types...................................................................................................... 57

TSFaxParam structure................................................................................................................................................... 57

TSPortStatus structure.............................................................................................................................................. 61

TUFaxImage union................................................................................................................................................................ 64

TSTestResult structure................................................................................................................................................ 65

TSFaxHeader structure................................................................................................................................................. 66

TSHeaderRecord structure........................................................................................................................................ 70

TSHeaderContext structure....................................................................................................................................... 71

TSSessionParameters structure.............................................................................................................................. 72

TSReceivedPageData structure............................................................................................................................... 77

FAXCPP Classes and Functions.............................................................................................. 78

Driver Initialization........................................................................................................................................................... 78

SetupFaxDriver........................................................................................................................................................ 78

Close Driver......................................................................................................................................................................... 83

EndOfFaxDriver........................................................................................................................................................ 83

COM Port Handler Functions..................................................................................................................................... 84

ConnectPort............................................................................................................................................................... 84

ConnectPortExt...................................................................................................................................................... 86

ConnectPortHandle............................................................................................................................................. 88

ConnectPortHandleExt..................................................................................................................................... 89

GetPortID...................................................................................................................................................................... 90

DisconnectPort....................................................................................................................................................... 91

EnableFaxPort.......................................................................................................................................................... 92

IsFaxPortEnabled.................................................................................................................................................. 93

IsPortVoice.................................................................................................................................................................. 94

SetModemCommands............................................................................................................................................. 95

GetPortStatus......................................................................................................................................................... 96

DisablePort................................................................................................................................................................. 99

PortCapabilities................................................................................................................................................... 100

SetPortCapabilities........................................................................................................................................... 102

AbortPort.................................................................................................................................................................. 105

DeleteAllPort......................................................................................................................................................... 106

GetNumberOfPorts............................................................................................................................................. 107

EnableTasks............................................................................................................................................................. 108

SetSpeaker................................................................................................................................................................ 109

SetDialMode.............................................................................................................................................................. 110

CreatePort................................................................................................................................................................ 111

ConnectToCommPort......................................................................................................................................... 112

DisconnectToCommPort................................................................................................................................. 113

DeleteCommPort................................................................................................................................................... 114

LoadPortSetting................................................................................................................................................... 116

IsPortOpen................................................................................................................................................................. 117

GetDeviceHandle................................................................................................................................................... 118

SetModemCommand............................................................................................................................................. 119

SetCommandTimeout.......................................................................................................................................... 121

GetModemCommand............................................................................................................................................. 123

GetCommandTimeout.......................................................................................................................................... 124

SetupCommPort..................................................................................................................................................... 125

GetCommPortSetting........................................................................................................................................ 127

SetupPortCapabilities..................................................................................................................................... 129

GetPortSetting..................................................................................................................................................... 132

GetModemCapability.......................................................................................................................................... 135

GetCapability........................................................................................................................................................... 137

GetRemoteModemCapability....................................................................................................................... 140

GetSessionParameters.................................................................................................................................. 142

ConnectChannel.................................................................................................................................................... 146

ComBoard.................................................................................................................................................................... 148

Sending and Receiving Faxes...................................................................................................................................... 149

CreateSendFax....................................................................................................................................................... 149

SetFaxImagePage................................................................................................................................................. 151

GetAllFaxType........................................................................................................................................................ 155

PutFaxOnQueue...................................................................................................................................................... 156

GetPriority................................................................................................................................................................ 158

SetPriority................................................................................................................................................................ 159

GetUserString........................................................................................................................................................ 160

SetUserString........................................................................................................................................................ 161

SendFaxNow.............................................................................................................................................................. 162

SetFaxMessage...................................................................................................................................................... 164

KillFaxMessage...................................................................................................................................................... 166

GetFaxParam............................................................................................................................................................ 167

GetFaxImagePage................................................................................................................................................. 168

ManualAnswer........................................................................................................................................................ 171

SetAutoAnswer..................................................................................................................................................... 172

SetNextFax................................................................................................................................................................ 173

GetDTMFDigits.......................................................................................................................................................... 174

Queue Functions.............................................................................................................................................................. 175

GetObjFromSendQueue.................................................................................................................................... 175

GetObjFromReceiveQueue............................................................................................................................ 176

GetNextFaxQueueObj........................................................................................................................................ 177

PutFaxOnQueue...................................................................................................................................................... 178

ClearFaxObj.............................................................................................................................................................. 180

Miscellaneous Functions............................................................................................................................................ 181

EnableLog................................................................................................................................................................... 181

SetLogDir.................................................................................................................................................................... 182

SetMyID.......................................................................................................................................................................... 183

SetStationID............................................................................................................................................................. 184

SetFaxObjDir............................................................................................................................................................ 186

GetFaxCppVersion............................................................................................................................................... 187

GetNumberOfLicensedPorts....................................................................................................................... 188

SetRuningMode....................................................................................................................................................... 189

GetRuningMode....................................................................................................................................................... 191

PostRegMessage.................................................................................................................................................. 192

GetFaxSystemDialogBox................................................................................................................................ 193

DetectDialTone...................................................................................................................................................... 194

FaxModemTest......................................................................................................................................................... 195

SetResponseString............................................................................................................................................ 196

GetResponseString............................................................................................................................................ 198

SetVoiceTimeout................................................................................................................................................... 199

GetDID............................................................................................................................................................................. 200

SetPhaseCoverage............................................................................................................................................. 201

SetDigitNumber...................................................................................................................................................... 202

SetPrefix..................................................................................................................................................................... 203

GetPrefix.................................................................................................................................................................... 204

WaitForObject........................................................................................................................................................ 205

ReleaseObject........................................................................................................................................................ 206

ReturnErrorString............................................................................................................................................ 207

EnableBitOrderDetect.................................................................................................................................... 209

DisableBitOrderDetect................................................................................................................................... 210

IsSubaddressEnabled....................................................................................................................................... 211

EnableSubaddress.............................................................................................................................................. 212

GetFaxType................................................................................................................................................................ 213

Fax Header Functions.................................................................................................................................................... 214

SetFaxHeader.......................................................................................................................................................... 214

Fax Object Save And Load Functions..................................................................................................................... 216

WriteHeader............................................................................................................................................................. 216

WriteHeaderExt.................................................................................................................................................... 217

ReadHeader............................................................................................................................................................... 219

ReadHeaderExt....................................................................................................................................................... 220

WriteImgData........................................................................................................................................................... 221

ReadImgData............................................................................................................................................................. 222

Write............................................................................................................................................................................... 223

Read................................................................................................................................................................................. 224

Brooktrout Functions................................................................................................................................................. 225

IsBrooktrout........................................................................................................................................................... 225

B_GetChannelInfo................................................................................................................................................ 226

B_IsChannelFree.................................................................................................................................................... 227

B_SetHeader............................................................................................................................................................. 228

B_SetHeaderType.................................................................................................................................................. 230

EnableDebug............................................................................................................................................................. 231

TestBrooktrout.................................................................................................................................................... 232

B_DialDBCheck......................................................................................................................................................... 233

B_GetDID........................................................................................................................................................................ 236

B_SetDigitNumber................................................................................................................................................. 237

B_SetVoiceTimeout.............................................................................................................................................. 238

B_SetVoiceFile........................................................................................................................................................ 239

GammaLink Functions..................................................................................................................................................... 240

Gamma Special File retreval...................................................................................................................... 240

G_IsGamma................................................................................................................................................................... 241

G_GetChannelNum................................................................................................................................................. 242

G_IsChannelFree................................................................................................................................................... 243

G_SetHeader............................................................................................................................................................. 244

G_GetLastStatus.................................................................................................................................................. 245

TestGammaLink........................................................................................................................................................ 246

ReturnPageFile...................................................................................................................................................... 247

IsPageFileReturned............................................................................................................................................ 248

GetLastPageFileName....................................................................................................................................... 249

Dialogic Functions......................................................................................................................................................... 251

D_GetBoardNum...................................................................................................................................................... 251

D_GetChannelNum................................................................................................................................................. 252

D_IsChannelFree.................................................................................................................................................... 253

D_HeaderMode......................................................................................................................................................... 254

D_HeaderDateFormat........................................................................................................................................ 256

D_HeaderTimeFormat......................................................................................................................................... 257

D_HeaderDateTimeString............................................................................................................................... 258

D_HeaderStartPage........................................................................................................................................... 259

D_HeaderUser1........................................................................................................................................................ 260

D_HeaderUser2........................................................................................................................................................ 261

TestDialogic............................................................................................................................................................. 262

Natural Microsystems Functions........................................................................................................................... 263

NMS_GetBoardNum............................................................................................................................................... 263

NMS_GetChannelNum.......................................................................................................................................... 264

NMS_IsChannelFree............................................................................................................................................. 265

NMS_SetDIDDigitNumber................................................................................................................................... 266

NMS_SetDigitTimers............................................................................................................................................ 267

TestNMS........................................................................................................................................................................ 268

NMS_SetProtocol................................................................................................................................................. 269

NMS_GetChannelState...................................................................................................................................... 271

NMS_TestChannel.................................................................................................................................................. 272

TCFaxNormal class......................................................................................................................................................... 273

CreateFaxObj.......................................................................................................................................................... 273

RegisterFaxClass................................................................................................................................................ 274

GetAllFaxClass...................................................................................................................................................... 275

SetParam..................................................................................................................................................................... 276

SetImagePage.......................................................................................................................................................... 277

GetParam..................................................................................................................................................................... 280

GetSessionParam................................................................................................................................................. 281

GetImagePage.......................................................................................................................................................... 282

GetCompatibleFaxType.................................................................................................................................... 284

StartFax...................................................................................................................................................................... 285

StartPage................................................................................................................................................................... 286

WriteData................................................................................................................................................................... 287

ReadData...................................................................................................................................................................... 288

EndPage........................................................................................................................................................................ 289

EndFax............................................................................................................................................................................ 290

TCQueue class................................................................................................................................................................... 291

GetItemNumber....................................................................................................................................................... 291

GetFirstItem............................................................................................................................................................. 292

GetEndItem................................................................................................................................................................. 293

GetQueueType......................................................................................................................................................... 294

ChainInFirst............................................................................................................................................................... 295

ChainInEnd................................................................................................................................................................... 296

ChainInItem................................................................................................................................................................. 297

ChainInItemWithPriority................................................................................................................................. 298

ChainOutItem............................................................................................................................................................ 299

TCQueueItem class........................................................................................................................................................... 300

ChainInItem................................................................................................................................................................. 300

ChainOutItem............................................................................................................................................................ 301

GetPrevItem.............................................................................................................................................................. 302

GetNextItem.............................................................................................................................................................. 303

GetQueueForItem................................................................................................................................................. 304

C Queue Functions.......................................................................................................................................................... 305

GetReceiveQueue.................................................................................................................................................. 305

GetSendQueue......................................................................................................................................................... 306

SetAllQueues........................................................................................................................................................... 307

BFT Send and Receive Functions.............................................................................................................................. 308

TEBftAction enum................................................................................................................................................. 308

TEScanLine enum.................................................................................................................................................... 308

TEFaxError enum.................................................................................................................................................. 308

TSFaxTime struct.................................................................................................................................................. 309

TCBinaryParam enum.......................................................................................................................................... 309

TCBinaryParam class..................................................................................................................................................... 312

WriteValue................................................................................................................................................................. 312

ReadValue................................................................................................................................................................... 313

AddNewBinaryParam.......................................................................................................................................... 314

GetNextBinaryParam......................................................................................................................................... 315

GetLastBinaryParam......................................................................................................................................... 316

ClearAllData............................................................................................................................................................ 317

G5 Messaging..................................................................................................................................................................... 318

1. Enabling G5 Messaging in Fax C++...................................................................................................... 318

2. New G5 Fax Messages:................................................................................................................................. 318

3. New termination codes:............................................................................................................................. 319

4. New G5 functions............................................................................................................................................. 320

G5ConfirmationEnabled.................................................................................................................................. 320

G5EnableConfirmation..................................................................................................................................... 321

OnCheckTurnAround.......................................................................................................................................... 322

OnSendDocument.................................................................................................................................................. 323

OnReplyFileFormat............................................................................................................................................. 324

OnSendConfirmation.......................................................................................................................................... 325

SetG3FaxObj.............................................................................................................................................................. 326

GetG3FaxObj............................................................................................................................................................. 327

Email To Fax, Fax To Email Add-on........................................................................................ 328

Overview............................................................................................................................................................................... 328

Directory structure..................................................................................................................................................... 329

Email To Fax, Fax To Email data types..................................................................................................................... 330

M_DATA............................................................................................................................................................................ 330

S_DATA............................................................................................................................................................................ 331

Function reference........................................................................................................................................................ 332

GetEmail....................................................................................................................................................................... 332

SendEmail.................................................................................................................................................................... 334

Sample Applications............................................................................................................... 335

Description of the sample applications................................................................................................................ 335

DLL Samples............................................................................................................................................................... 336

TempFileInfo................................................................................................................................................................. 336

FaxWithBrooktrout........................................................................................................................................................ 338

Multiport Faxing............................................................................................................................................................ 339

SIMPLE.......................................................................................................................................................................... 339

SERVICE........................................................................................................................................................................ 340

DEMO32........................................................................................................................................................................ 340

OpenComPorts............................................................................................................................................................. 342

OpenFaxBoards........................................................................................................................................................... 342

Queue Priority Sample................................................................................................................................................ 343

ReceiveFax.................................................................................................................................................................... 344

ReceiveFaxWithDMTF................................................................................................................................................. 346

RetrySample................................................................................................................................................................. 346

SendFax......................................................................................................................................................................... 347

DOT NET Samples.................................................................................................................................................... 349

Fax OCX C# Demo...................................................................................................................................................... 349

C# OpenComPorts Sample....................................................................................................................................... 350

C# OpenFaxBoards Sample...................................................................................................................................... 351

C# Queue Priority Fax Sample.................................................................................................................................. 352

C# ReceiveFax Sample.............................................................................................................................................. 353

C# ReceiveFaxWithDTMF Sample........................................................................................................................... 355

C# Retry Sample.......................................................................................................................................................... 356

C# SendFax Sample................................................................................................................................................... 358

Faxcpp .NET VB Sample............................................................................................................................................ 359

.NET VB OpenComPorts Sample............................................................................................................................. 360

.NET VB OpenFaxBoards Sample............................................................................................................................ 362

.NET VB Queue Priority Sample............................................................................................................................... 363

.NET VB ReceiveFax Sample.................................................................................................................................... 364

.NET VB ReceiveFaxWithDTMF Sample................................................................................................................. 366

.NET VB Retry Sample................................................................................................................................................ 367

.NET VB SendFax Sample......................................................................................................................................... 369

OCX Samples.............................................................................................................................................................. 370

CPP Sample................................................................................................................................................................. 370

Delphi Sample.............................................................................................................................................................. 371

Delphi OpenComPorts Sample................................................................................................................................ 372

Delphi OpenFaxBoards Sample............................................................................................................................... 373

Delphi Queue Priority Sample................................................................................................................................... 373

Delphi ReceiveFax Sample....................................................................................................................................... 374

Delphi ReceiveFaxWithDTMF Sample.................................................................................................................... 375

Delphi SendFax Sample............................................................................................................................................ 376

FoxPro............................................................................................................................................................................ 377

Visual Basic Sample................................................................................................................................................... 378

Visual Basic OpenComPorts Sample...................................................................................................................... 379

Visual Basic OpenFaxBoards Sample..................................................................................................................... 380

Visual Basic Queue Priority Sample........................................................................................................................ 380

Visual Basic ReceiveFax Sample............................................................................................................................. 381

Visual Basic ReceiveFaxWithDTMF Sample.......................................................................................................... 382

Visual Basic Retry Sample......................................................................................................................................... 383

Visual Basic SendFax Sample.................................................................................................................................. 384

Troubleshooting..................................................................................................................... 386

Inverted Faxes................................................................................................................................................................... 386

Getting an 'Invalid remote length' termination code..................................................................................... 386

What does the TRM_RESENDPAGE mean............................................................................................................. 387

Where to find the parameter constant declarations.................................................................................. 387

Where to find the Error Code Defines................................................................................................................ 387

What is the difference between the FEV_XXX and MFX_XXX messages?............................................ 387

Is it necessary for the application to provide a window handle and handle messages sent by Fax C++? 388

Can I use the Fax C++/OCX in a service?................................................................................................................. 388

Do I need drivers for my Brooktrout, Dialogic, GammaLink or NMS board?.................................... 388

The board drivers are already installed and configured but Fax C++ still does not recognize the board. Why?................................................................................................................................................................................................... 389

What version of the board drivers are supported by Fax C++ and how do i get them?............... 389

Can I use Brooktrout TR114 or TruFax boards with Brooktrout Tr1034 boards in the same machine? 389

Can I use multiple boards or board types in the same machine?................................................................ 390

Can I access the same board from two different applications?.............................................................. 390

The received fax has some garbage lines. Why does this happen and how do i fix it?..................... 390

What happens with fax pages that are received partially because of transmission errors?... 390

What information does the Fax C++ log file contain and how can I display it?............................... 390

Can I abort a fax which is being sent with a Gammalink board?................................................................. 391

Is the Fax C++ SDK multithreaded?......................................................................................................................... 391

The faxcpp1.ini file shipped with older versions of Fax C++ contained settings for several hundred modems. The faxcpp1.ini file shipped with newer versions of the product contains settings for only a few modems. Why were these settings removed?.............................................................................................................................................. 391

When can a fax object be deleted?.......................................................................................................................... 391

Can a fax object be re-used?...................................................................................................................................... 391

I'm trying to add a fax header to a fax page but no header is added....................................................... 392

When I send a fax with fine resolution, the receiver receives the fax but the received page is compressed to half of its original size. Why?............................................................................................................................................. 392

Can the application perform time consuming operations when it handles fax messages or events? 392

Is Fax/Voice C++ .NET compatible?........................................................................................................................... 392

Do I need to licence the Fax C++ in order to send faxes with Voice C++?.......................................... 392

Is Binary File Transfer and color faxing supported by fax boards with Fax C++?......................... 392

I have a DSL modem, can I use it with the product?.......................................................................................... 393

I have a Cable modem, can I use it with the product?...................................................................................... 393

Does Fax C++ support IP faxing?............................................................................................................................. 393

I can't get Fax C++ to work with Brooktrout hardware on Windows Server 2003...................... 393

If I have a transmission failure and want to re-use the FaxID, how much information does the object connected to the FaxID contain (can we reuse all the methods and properties and is the fax tiff-file still included in the object)?................................................................................................................................................................................ 393

When is the FaxID released from the previous transmission ?.................................................................. 394

When you recieve events from the component, which thread is used (main or ??)?....................... 394

What image/file format is the natural format for Sending and receiveing faxes?....................... 394

Can I send a Word, Excel, HTML, etc file as a fax?........................................................................................... 394

How can I convert text into a fax?......................................................................................................................... 394

What is the order of messages my application should receive when faxing?................................... 395

Some of my Dialogic channels do not answer when using every channel.......................................... 395

Error Codes.............................................................................................................................. 396

Termination Status Codes..................................................................................................... 399

Fax messages............................................................................................................................ 405

History....................................................................................................................................... 408

Appendices................................................................................................................................. 414

INDEX............................................................................................................................................ 415