Integrated Voice and Data Software Support in Microsoft Windows

Microsoft Windows

File Transfer API and VoiceView Sockets API

Windows Sockets Version 1.1

Microsoft Windows Future Version

Microsoft Corporation

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

© 1994 Microsoft Corporation. All rights reserved.

Microsoft, MS, MS-DOS, and Microsoft PowerPoint are registered trademarks of Microsoft Corporation in the USA and other countries.

U.S. Patent No. 4955066

Radish is a trademark and VoiceView is a registered trademark of Radish Communications Systems, Inc.

UNIX is a registered trademark of Unix Systems Laboratories, Inc.

Printed in the United States of America.


Introduction

VoiceViewÒ is a communications technology that allows both voice and data communications to take place during the same telephone call. By integrating voice and data, an ordinary voice telephone call can include the exchange of data, graphics, or other digital information.

Integrated voice and data enhances what people can do during a telephone call by integrating the use of computers with person-to-person or person – to – voice-processing system communications. Computers add the viewing and manipulation of shared information to a normal telephone conversation.

Communications hardware implements the technology. A VoiceView-capable modem allows a user to take advantage of that technology. The modem can be part of a motherboard of a personal computer, part of an internal, PCMCIA, or external modem, or part of a multifunction card based on digital-signal-processing technology. Handheld computers, voice-response systems, screen phones, and other devices based on embedded software will also include technology and will communicate with VoiceView-capable personal computers.

Modem and voice-processing companies have already widely accepted VoiceView due to its attractive price, its ease of implementation, and its compatibility with existing data and telecommunications products. VoiceView works over a single analog telephone line or transparently across proprietary digital PBX or Key systems.

Starting in 1995, many computers running MicrosoftÒ WindowsÔ will be VoiceView-capable or will use VoiceView-enabled modems. This document describes how the developer of Windows applications can take advantage of integrated voice and data capabilities in those systems.

Organization of This Manual

This manual consist of five chapters. Here is a brief description of each:

  • Chapter 1, "Integrating Voice and Data: Overview," describes the VoiceView protocol and its operation, potential applications, and software support for application development in Microsoft Windows.
  • Chapter 2, "File Transfer API Guide," discusses concepts and use of the File Transfer applications programming interface (API) in Microsoft Windows.
  • Chapter 3, "File Transfer API Reference," provides an alphabetic listing of items in the File Transfer API.
  • Chapter 4, "Sockets API Guide," discusses concepts and use of the VoiceView Sockets API in Microsoft Windows.
  • Chapter 5, "Sockets API Reference," provides an alphabetic listing of items in the VoiceView Sockets API.

Disclaimer

This document is preliminary and may change substantially prior to final commercial release. Microsoft Corporation provides this document for informational purposes only, and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user.

Document Conventions

This document uses these conventions to define syntax:

Convention

Meaning

Bold text

Denotes a literal term or character, such as a reserved word or a function name. Type this term exactly as shown.

Italic text

Denotes a placeholder or variable. Provide an actual value or name when you use this.

FULL CAPITALS

Indicate filenames and paths, many macro names, data types, structure names (which are also bold), and constants.

monospace

Sets off code examples and shows syntax spacing.


Chapter 1 Integrating Voice and Data: Overview

CHAPTER 1

Integrating Voice and Data: Overview

There are a number of technologies that allow both voice and data to be exchanged on a single phone call without having to hang up. By exploiting this capability, a variety of new applications can be constructed that make the everyday telephone call a richer experience.

The first of these technologies to be broadly available is VoiceView, which is an alternating voice and data protocol for hardware devices and software applications that optimizes the integration of voice and data communications. VoiceView allows a software application to very quickly switch back and forth between sending voice and sending data on a call.

Voice-aware applications benefit the user by using a computer to enhance communications during normal telephone calls. The power of the computer increases the amount and accuracy of exchanged information and decreases the time for a call. New types of interaction, which are not possible in either a standard data call or a standard voice call, also become available. Applications for Microsoft Windows incorporate these benefits of VoiceView and other voice-data technologies (such as simultaneous voice-data or ultimately ISDN) by using the File Transfer API and the Windows Sockets API.


1.1 VoiceView Protocol

Radish Communications Systems, Inc. of Boulder, Colorado licenses the VoiceView protocol to hardware manufacturers for use in their communications equipment. Most modem chipset and hardware manufacturers have licensed this protocol for inclusion in their product. Software developers create applications that use VoiceView-enabled hardware, and they need not license the protocol. The features of VoiceView-enabled hardware and VoiceView-aware software operate to achieve specific communications goals.


1.1.1 Goals

The major goals of the VoiceView protocol are:

  • To temporarily establish a data connection during a voice call with another party, to quickly exchange information with that party, and then to immediately return to the voice mode for continued discussion.
  • To enhance automated voice transactions with an automated response system, such as a voice mail system or voice response unit.


1.1.2 Operation

VoiceView works by switching the telephone line between voice and data communication modes. Voice and data communications occur in the same way they do today, but both share the same call. Voice communications and data communications each use the full bandwidth of the telephone line to deliver information during operation of the respective mode.

Voice mode is the default mode of operation. When in this mode, VoiceView-enabled equipment transparently behaves as normal telephone equipment. However, the equipment monitors the communications connection and the data connection for specific events and changes its mode appropriately in response.

When one person wants to send data to the other person on a call, the sending modem temporarily mutes the handset and sends a signal directing the other modem to switch to data mode. When the receiving modem receives the signal, it mutes its handset and prepares to receive data. After transferring the data, both modems unmute their handsets and normal conversation continues.

VoiceView supports switching into a special data mode that is optimized for quickly sending data and returning to voice mode. Using this special data mode, 2K of error-corrected data can transfer with only a three-second interruption in the conversation.

VoiceView-enabled equipment also includes a capabilities query that determines if equipment at the far end of a connection is VoiceView-enabled, and if so, what capabilities the equipment has. This feature allows VoiceView equipment to adapt to, and to optimize communications for, each connection.


1.2 Software Applications

A broad range of software applications benefit from the integration of voice and data on a single call. The following descriptions of possible examples illustrate potential applications.

  • File transfer during a voice telephone call
  • A personal computer user simply drags and drops a file icon onto a file transfer application or its icon. VoiceView puts the callers on hold, transfers the file, and then returns the callers to normal conversation. Using this feature, business associates who are discussing a document — such as a business sales forecast, a financial plan, or a marketing proposal — easily exchange and modify that document or other data during a voice phone call.
  • Multimedia phone call
  • During a conversation, one party displays graphical information on the other party's screen instead of just describing the information over the phone. For instance, a broker displays a graph of portfolio growth, a real-estate agent displays a picture of a house, or a customer representative displays the status of an order.
  • Remote presentation
  • A personal computer user with presentation software such as Microsoft PowerPoint sends a presentation slide by slide to another user, regardless of location.
  • Instant visual confirmation
  • Business transactions conducted by phone occur in a single call, rather than requiring a number of different phone calls and faxes. The transaction involves the immediate display, modification, and approval of a payment receipt, purchase order, or deposit form. A transmitted digital signature instantly confirms the transaction.
  • Remote hardware and software support
  • A support technician accesses system configuration and diagnostic information during a support call. The technician also transfers required driver software, switches to remote control software, fixes the user's problem, and returns to voice mode to discuss the results with the user.
  • Visual voice-response application
  • Airlines, banks, insurance companies, catalog companies, and other service providers heavily use voice-response technology. In a current, typical case, a customer calls a bank for account information and receives only a spoken account balance at the conclusion of a long, frustrating interaction with computerized voice commands. Instead, a customer using a VoiceView-aware application uses a graphical user interface to retrieve a complete statement of account.
  • Graphical interface to voice mail
  • A remote caller sees a list of voice-mail messages with the names of senders and then selects any desired message to play. Recipients no longer need to play through the first 14 messages to hear the 15th one, if that one is most important. Callers also leave a file or a fax during a voice message.
  • Business card exchange during a phone call
  • A business person provides pertinent information to another during a phone call. Instead of verbally conveying the information — a time-consuming, error-prone process — a click of the mouse instantly sends a business card and automatically inserts it into a remote address book.
  • Multiplayer games
  • Two people play a game over the telephone network while continuing to talk to each other.

Some of these examples involve adding voice-awareness to an existing application. Other examples involve a completely new software application.


1.3 Windows Software Support

Microsoft Windows provides VoiceView extensions to the Windows Sockets API for the application developer to use when transferring data between VoiceView-enabled devices. Microsoft Windows also provides the File Transfer API to easily accomplish a few well-defined file-transfer tasks using the Windows Sockets API (as well as APIs for other transport mechanisms.)

Microsoft Windows interacts with a VoiceView-enabled device by sending and receiving messages through the serial communications interface. The messages use an extension to the AT-type commands of the TIA/EIA – 602 and TIA/EIA – 615 standards.

In the future, Microsoft will add support for further voice and data integration technologies. Simultaneous Voice-Data (SVD) lets users talk and transmit data at the same time on an analog phone line (as opposed to VoiceView, which flips between voice and data). Ultimately, this architecture will scale to ISDN.

The following figure shows the structure of a typical that uses a VoiceView-enabled modem with a serial connection to the computer running the application and connections to the telephone network and a local telephone.


1.3.1 File Transfer API

The File Transfer API provides a simple interface to lower-level APIs, including the WindowsSockets API. You use calls to the File Transfer API to transfer one or more files to a remote application through a VoiceView-enabled modem. An application on the remote computer directly receives the transferred files, or a system-provided, default file transfer application receives the files.

Chapter 2, "File Transfer API Guide," discusses concepts and programming topics for the File Transfer API. Chapter 3, "File Transfer API Reference," provides details on each of the items of the API.


1.3.2 Windows Sockets

The VoiceView Sockets extensions to the Window Sockets API provide a low-level interface to the communications layer of Microsoft Windows. You use sockets when you need to exercise fine control over the VoiceView hardware device and when the File Transfer API provides insufficient functionality for a particular application.

Chapter 4, "VoiceView Sockets API Guide," discusses concepts and programming topics for the VoiceView Sockets API. Chapter 5, "VoiceView Sockets API Reference," provides details on each of the items of the API.


Chapter 2 File Transfer API Guide

CHAPTER 2

File Transfer API Guide

The Windows File Transfer applications programming interface transfers files over VoiceView modems and other types of communications hardware using several transport mechanisms, including the VoiceView Sockets API. The File Transfer API forms a task-oriented layer, built on top of lower-level APIs such as the Windows Sockets API, that simplifies file transfers.

This chapter outlines transferring files using the File Transfer API. The first section discusses important ideas related to the use of the API, and the second section outlines typical programming tasks using the API. Chapter 3, "File Transfer API Reference," includes details for all File Transfer API items.


2.1 Understanding the File Transfer API

The File Transfer API sends and receives files in one of several modes between two computers connected by a communications network. One or more applications can be used to transfer the files, either automatically, or with user interaction. Many aspects of the file transfers occur automatically, because the file transfer applications intelligently use options such as transmitted headers, compression, events, and automatic launching of other applications during the file transfer process.


2.1.1 Application Types

Applications that use the File Transfer API are in one of two categories. An application either transfers files for a specific application, or it is the default file transfer application.


2.1.1.1 Specific Application

A universal, unique identifier (UUID) identifies a specific application. The developer of a specific application assigns the UUID to that application. (See UUID in Chapter 3 for details on how to obtain a UUID.) Any application (whether it is the specific application or not) can use that UUID when it establishes a file transfer session using the xfInitialize function, if it can transfer files for the specific application. An application that can transfer files for more than one specific application is able to support multiple UUIDs.


2.1.1.2 Default Application

A default file transfer application should always be available to send and receive an arbitrary file. The default application should make the received files easy to access so that the user can open, delete, or save each file. Microsoft provides a default file transfer application along with the Microsoft File Transfer API. It can be replaced with one from an alternative source or one that has been specially created

Such an application that transfers the files of all specific applications must identify itself by using the xfRegister function call to register itself as the default application.


2.1.2 File Transfer Modes

There are three distinct modes of file transfers. The allowable receiving application is able to distinguish between these modes.


2.1.2.1 Sending to the Default Application

In the first mode, the sending application chooses the default application as the allowable destination. This mode is the programmatic equivalent of the user sending a file by interactively using the default file transfer application.

To select this mode, the sending application does not specify the XF_MATCHID option in the xfSend or xfConnectAndSend function call. The sending application does use a connection made (with an xfConnect function call for the xfSend function, or as part of the xfConnectAndSend function call) with an XFRADDRESS structure that specifies a NULL in the uuidAppID field. With this combination of parameters, the default application receives the file transfer.


2.1.2.2 Sending to Specific, or Default Application

In the second mode, the sending application chooses as first priority the application registered on the receiving machine for the specified UUID for the allowable destination application. If available, the application opens and displays the file. If that application is not available, the default file transfer application receives the file transfer.

To select this mode, the sending application does not specify the XF_MATCHID option in the xfSend or xfConnectAndSend function call. The sending application does use a connection made (with an xfConnect function call for the xfSend function, or as part of the xfConnectAndSend function call) with an XFRADDRESS structure that specifies the specific UUID in the uuidAppID field. With this combination of parameters, the specific application receives the file transfer if it is available. Otherwise, the default application receives the file transfer.


2.1.2.3 Private Transfers to Specific Application

In the third mode, the only allowable destination application is the specific application registered on the receiving machine for the specified application UUID. Private transfers usually involve two instances of the same application, one running on each machine.

To select this mode, the sending application specifies the XF_MATCHID option in the xfSend or xfConnectAndSend function call. The sending application also uses a connection made (with an xfConnect function call for the xfSend function, or as part of the xfConnectAndSend function call) with an XFRADDRESS structure that specifies the specific UUID in the uuidAppID field. With this combination of parameters, only the specific application can receive the file transfer. Otherwise, the file transfer fails.


2.1.3 User Interaction

User interaction with a file transfer application can be handled by a default interface or by a customized, non-default interface.


2.1.3.2 Default Interface

In a completely default interface, the file transfer application handles all events connected with the user interface and the progress dialog box provided by the file transfer engine. The file transfer engine sends user interface events to the xfNotifyProc function that the application provides, and that function passes all events connected with the user interface to the xfDefNotifyProc function for default interaction.


2.1.3.1 Custom Interface

In a completely custom interface, the file transfer application handles all events connected with the user interface and provides custom dialog boxes and message boxes for the user. The file transfer engine sends user interface events to the xfNotifyProc function that the application provides, and that function calls appropriate custom code.

Note that custom interfaces need to provide for determining the user's acceptance of incoming files, whether it is through a dialog that is presented with each collection of received files or a setting that applies to all received files.


2.1.4 Transfer Options

Other options associated with the file transfer provide flexibility for file transfer applications. These options include the ability to transfer arbitrary information besides that found in files (in the form of a "tag"), the ability to compress data to reduce transfer time, the availability of a wide range of events that the application can use to guide its processing, and the ability to launch automatically specific applications to process transferred files.


2.1.4.1 Tag Information

File transfer applications can transfer information in addition to, and to accompany, the information in the transferred files. The sending application can transfer the information as part of the arbitrary data in the lpTag parameter of the xfSend and xfConnectAndSend function calls. The receiving application can use the xfGetStatusLong function call to retrieve this information.

The information could instruct a specific word-processing application where to position a cursor after opening the transferred file. The information could also be the sole information transferred in the connection, with no accompanying files. This provides for a crude, interprocess connection between computers.


2.1.4.2 Data Compression

The file transfer engine automatically compresses the data in the files before sending and decompresses it after reception. An application can select not to compress the data by using the XF_DONT_COMPRESS option of the xfConnect function call. Note that the tag data is never compressed.


2.1.4.3 File Transfer Events

The file transfer engine transmits events to the xfNotifyProc function involving connections, file transfers, the user interface, and user actions at both ends of the connection. These constants describe the events that occur:

Value | Meaning
XFN_CONNECTION_ABORT | Connection abnormally terminating.
XFN_CONNECTION_END | Connection normally closing.
XFN_CONNECTION_START | Connection starting.
XFN_FILE_ABORT | File transfer abnormally terminating.
XFN_FILE_BLOCK | Transfer of one block of data complete.
XFN_FILE_END | File transfer normally closing.
XFN_FILE_START | File transfer starting.
XFN_TRANSFER_ABORT | Transfer abnormally terminating.
XFN_TRANSFER_ACCEPT | The receiver is notified that the transfer is accepted.
XFN_TRANSFER_CONFIRMED | The sender is notified that the transfer is confirmed.
XFN_TRANSFER_DECLINED | The send is notified that the transfer is declined.
XFN_TRANSFER_END | Transfer normally closing.
XFN_TRANSFER_START | Transfer starting.
XFN_TRANSFER_REFUSE | The receiver is notified that the current application declined the transfer.
XFN_UI_CONNECT | User interface connect notification. See dwParam for meaning.
XFN_UI_CONFIRMTRANSFER | Transfer about to start. The receiver's notification procedure should ask the user to confirm acceptance of transfer when notification is received. Return TRUE if transfer is OK, FALSE if not.
XFN_UI_DISCONNECT | User interface disconnect notification. See dwParam for meaning.
XFN_UI_TRANSFER | User interface transfer notification. See dwParam for meaning.


2.1.4.4 AutoLaunch Application

If a remote application sends a file for a specific application and that specific application is not running on the local computer, the file transfer engine can automatically launch the specific application and notify it of the pending transfer. To allow autolaunch, the application must first register appropriately with the file transfer engine using the xfRegister function call.


2.1.4.5 AutoOpen File

When a remote application sends a file to the default file transfer application, it can specify that the file transfer engine start the application associated with a single file in the transfer. The default file transfer application opens this file as if the file were double-clicked in Microsoft Windows. This allows the transfer of a file and the processing of the information in the file even if the specific application is not file-transfer aware.


2.2 Programming the File Transfer API

This section briefly discusses programming with the File Transfer API. Note that the structure of this section roughly parallels that of the API function call hierarchy that is used when transferring files. Many specific details about function calls appear in the reference in Chapter 3.


2.2.1 Preparing A File Transfer Application

The xfRegister and the xfGetVersion function calls can be used at any logical time in a file transfer application. These calls depend minimally on other File Transfer API calls.


2.2.1.1 Registering

Use the xfRegister function call to associate a specific UUID with a file transfer application. The xfRegister function call can accomplish one or more of these tasks:

  • register or unregister the association of UUID and application.
  • register the application to launch automatically to process transferred files for the UUID.
  • register the application as the default file transfer application to receive files.

Only one application can be associated with a particular UUID, but any file transfer application can register more than one UUID. The last application to register as the default application or with a particular UUID becomes the current default file transfer application or the application associated with the particular UUID, respectively.

Usually, an application is registered when it is installed on a system. Alternatively, a specific application can be registered each time it is run.


2.2.1.2 Getting File Transfer Engine Version

Use the xfGetVersion function call at any time in a file transfer application to determine the version of the currently running file transfer engineThe return value can be used to determine if a file transfer application is compatible with the current engine. The return value can also be used as input to the xfInitialize function call if the file transfer application is built for another version of the engine, but it is still compatible with the current version.


2.2.1.3 Handling File Transfer Events

The xfNotifyProc function is provided by the application to handle file transfer events that occur during a session. This notification procedure should call xfDefNotifyProc to provide a default action for events that it does not handle.


2.2.2 Managing a Session

To transfer files, an application makes connections with other computers during sessions that service specific applications. A session is a thread that couples a specific UUID, a designated notification procedure to handle file transfer events, and selected options for the specific application UUID. A connection occurs during a session. It establishes a communications channel using a selected transport mechanism and a selected transport-specific address.


2.2.2.1 Initializing a Session

Use the xfInitialize function call to initialize the file transfer engine and begin a session. Input parameters to this function include the application UUID and the notification procedure to use during the session. An application should initialize a session for each UUID for which it has registered.


2.2.2.2 Making and Closing a Connection

Once the file transfer engine initializes a session, a file transfer application can make, use, and close connections with other computers. See Section 2.2.3, "Managing a Connection," for details about connections.


2.2.2.3 Transferring without a Prior Connection

An application also can send and receive files without first establishing a connection. The xfConnectAndSend function can be used to expedite file transfers when there is a well-defined transfer task to perform.

The xfConnectAndSend function call can be used to make a connection, transfer one or more files, and terminate the connection. Using this function call simplifies file transfers, but the complete list of files to transfer must be known before calling the function.


2.2.2.4 Getting Status Information

The xfGetStatusLong and xfGetStatusText function calls provide information about a specified session and connection. These functions provide descriptive information about the group of files in a transfer, status information about a file transfer, and the arbitrary information sent as a "tag" in the file transfer.


2.2.2.5 Terminating a Session

When an application is done using the file transfer engine for a specific UUID or wants to re-establish a different notification procedure for that UUID, it calls the xfUninitialize function to terminate the session. An xfUninitialize function call should accompany each xfInitialize call in the orderly operation of a file transfer application.


2.2.3 Managing a Connection

To provide a flexible, unstructured file transfer service, an application can make a connection and then use that connection to send and to receive files and information in an event-driven manner. For instance, a drag-and-drop file transfer application would make a connection and then transfer files as directed by the user.


2.2.3.1 Making a Connection

Use the xfConnect function call to make a connection. Input parameters to this function specify the session in which to make the connection, the transfer address structure XFRADDRESS, and options for the connection.


2.2.3.2 Sending over a Connection

The xfSend function call starts a file transfer of one or more files. It can include – or consist entirely of – accompanying, arbitrary data. Several xfSend function calls can occur during a connection.


2.2.3.3 Receiving over a Connection

When a remote machine attempts to send files, the file transfer engine calls the application's xfNotifyProc with XFN_UI_CONFIRMTRANSFER. If the application wants to receive the files, it should return 1. It will then get an XFN_TRANSFER_ACCEPT notification. The application should call xfReceive to specify the directory for the received file and begin the transfer process. At any time, the application can use the xfGetStatusText and xfGetStatusLong functions to retrieve information associated with the transfer.


2.2.3.4 Stopping a File Transfer

When an error condition occurs that necessitates an abnormal termination of the file transfer, the application uses the xfAbortTransfer function call to terminate the transfer. This function call stops any file transfers in progress on the connection and performs any necessary clean-up procedures for the file transfer engine.


2.2.3.5 Closing a Connection

When the file transfer application is finished with a connection, it uses the xfDisconnect function call to close the connection. An xfDisconnect function call should accompany each xfConnect call in the orderly operation of a file transfer application. If a file transfer is in progress when the application makes the xfDisconnect call, an implicit xfAbortTransfer function call occurs. After the xfDisconnect function call, the connection no longer is available for file transfers.


2.2.4 File Transfer Errors

These errors can occur during the operation of one or more of the File Transfer API calls. The error constants and their meanings are:

Value | Meaning
XF_SUCCESS | Successful operation.
XFERR_ABORT | Transfer was aborted.
XFERR_ALREADYEXISTS | Application ID already registered to another application.
XFERR_ENGINEPROBLEM | File transfer engine couldn't start, or internal file transfer engine error.
XFERR_INCOMPATIBLEVERSION | Incompatible version of the DLL.
XFERR_INVALIDPARAM | One or more invalid parameters.
XFERR_NOCONNECTION | Failure during a physical connection.
XFERR_NOTINITIALIZED | Specified session or connection is invalid.
XFERR_NOVVMODEM | Unable to open a VoiceView socket because a modem was not installed or was being used by another device.
XFERR_OUTOFDISKSPACE | Out of disk space.
XFERR_OUTOFMEMORY | File transfer engine out of memory.
XFERR_TIMEOUT | Connection failure due to timeout error.


Chapter 3 File Transfer API Reference

CHAPTER 3

File Transfer API Reference

This chapter describes, in alphabetic order, each item (data type, structure, macro, and function) of the File Transfer applications programming interface. Each description contains the syntax, purpose, and parameters of the item, and the descriptions of functions contain appropriate constants for flags and return values. Many descriptions also contain comments and cross references to associated elements.

The syntax for each item appears in C-language format. In the C-language source files, spell the item names exactly as shown, and use parameters in the given order. Use these items in applications by placing the directive:

#include <fte.h>

at the beginning of the source files.


HCONNECTION, LPHCONNECTION

#include <fte.h>

HCONNECTION hConnection; /* 32-bit connection handle */
LPHCONNECTION lphConnection; /* 32-bit pointer to connection handle */

Variables of types HCONNECTION and LPHCONNECTION specify a file transfer connection.

Parameters

hConnection

32-bit value used as a connection handle.

lphConnection

32-bit pointer to a connection handle.

Comments

A connection handle results from a call to the xfConnect function or from a file transfer engine call to the notification procedure. The connection handle remains valid until the application closes the connection with a call to the xfDisconnect function.

See Also

xfNotifyProc, xfAbortTransfer, xfConnect, xfDefNotifyProc, xfDisconnect, xfReceive, xfSend


HSESSION, LPHSESSION

#include <fte.h>

HSESSION hSession; /* 32-bit session handle */
LPHSESSION lphSession; /* 32-bit pointer to connection handle */

Variables of types HSESSION and LPHSESSION specify a file transfer session.

Parameters

hSession

32-bit value used as a session handle.

lphSession

32-bit pointer to a session handle.

Comments

A session handle results from a call to the xfInitialize function or from a file transfer engine call to the notification procedure. The session handle remains valid until the application concludes the session with a call to the xfUninitialize function.

See Also

xfNotifyProc, xfConnect, xfConnectAndSend, xfDefNotifyProc, xfGetStatusLong, xfGetStatusText, xfInitialize, xfUninitialize


UUID, LPCUUID

#include <fte.h>

UUID uuidAppID; /* 16-byte value containing application ID */
LPCUUID lpAppID; /* 32-bit pointer to application ID string */

Variables of types UUID and LPCUUID specify the unique identifier, the application ID, that determines which application is to receive incoming files of a particular type.

Parameters

uuidAppID

A 16-byte character string that contains the application ID.

lpAppID

32-bit pointer to a nonmodifiable, application ID character string.

Comments

To produce an application ID, use the EXTIDGEN.EXE or GUUIDGEN.EXE applications. Consult the release notes for the Microsoft Windows SDK for an alternative version. These applications generate a value that is guaranteed to be unique.

See Also

xfInitialize, XFRADDRESS, xfRegister


xfAbortTransfer

#include <fte.h>

DWORD WINAPI xfAbortTransfer(hConnection, dwFlags)
HCONNECTION hConnection; /* handle of connection to terminate */
DWORD dwFlags; /* flag specifying reason for termination */

The xfAbortTransfer function tells the system to terminate a file transfer.

Parameters

hConnection

Identifies the connection to terminate.

dwFlags

Specifies the conditions for termination. It can be one of the following:

Value | Meaning
XF_SYSTEM_ABORT | System specified termination due to error such as not enough disk space or fatal application error.
XF_USER_ABORT | User specified termination, for instance by choosing a cancel button.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

The xfAbortTransfer function is generally called after an error condition occurs and when abnormally terminating the transfer. Use the xfAbortTransfer function call after the application detects the error and needs to terminate the tranfer. The file transfer engine will stop receiving files on that connection and notifies the remote computer.

See Also

xfDisconnect


xfConnect

#include <fte.h>

DWORD WINAPI xfConnect(lphConnection, hSession, lpAddress, dwFlags)
LPHCONNECTION lphConnection; /* pointer to handle of resulting connection */
HSESSION hSession; /* handle of session to use for connection */
LPXFRADDRESS lpAddress; /* pointer to transfer address for connection */
DWORD dwFlags; /* flag specifying conditions for connection */

The xfConnect function opens a connection using the specified session and address and sets a connection handle.

Parameters

lphConnection

Identifies the resulting connection. If NULL, the connection failed.

hSession

Identifies the desired session, which a call to xfInitialize established.

lpAddress

Provides information (such as a telephone number or a machine name) needed about the transfer address to make the connection. See XFRADDRESS for details about the address structure.

dwFlags

Specifies optional conditions for the connection. It can be one, or a logical or, of these values:

Value | Meaning
XF_DONT_COMPRESS | Don't compress files when transferring them. If not specified, files are compressed for efficient transfer.
XF_MATCHID | Allow only the specific application with the UUID in the uuidAppID field of the XFRADDRESS to receive the files.
XF_WAIT | Wait until connection is made and verified before returning from the function call. If not specified, return immediately after requesting the connection.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

If the XF_WAIT flag is specified, the file transfer engine makes and verifies the connection before returning from the call. Otherwise, the call returns immediately. In this case, an XF_SUCCESS return value does not necessarily signify a successful operation, and the file transfer engine continues to complete the connection.

After making a successful xfConnect function call, multiple xfSend function calls can be made to send files using the connection. This capability facilitates transferring files when a complete list of files is not initially available.

Call the xfDisconnect function when you no longer need the connection.

If no UUID is specified in the uuidAppID field fo XFRADDRESS, the default application receives the files. If a UUID is specified, the files will be received by the application or by the default application if the application is not available. If a UUID is specified and the XF_MATCHID option is used, the files must be received by the specific application or the transfer fails.

See Also

xfConnectAndSend, xfDisconnect, xfInitialize, XFRADDRESS, xfSend


xfConnectAndSend

#include <fte.h>

DWORD WINAPI xfConnectAndSend(hSession, lpAddress, lpOpen, lpDescription, lpFiles, lpTag, lcbTag, dwFlags)
HSESSION hSession; /* handle of session to use for connection */
LPXFRADDRESS lpAddress; /* pointer to transfer address for connection */
LPCSTR lpOpen; /* pointer to parameter for receiving application */
LPCSTR lpDescription; /* pointer to friendly description of transfer */
LPCSTR lpFiles; /* pointer to list of files to transfer */
LPCSTR lpTag; /* pointer to arbitrary data for receiving application */
DWORD dwTag; /* number of bytes in tag */
DWORD dwFlags; /* flag specifying conditions for send */

The xfConnectAndSend function makes a connection, transfers file(s), and terminates the connection.

Parameters

hSession

Identifies the desired session, which was established by a call to xfInitialize.

lpAddress

Provides information (such as a telephone number or a machine name) needed about the transfer address to make the connection. See XFRADDRESS for details about the address structure.

lpOpen

Indicates the filename to open after the transfer is complete. This parameter is optional, and if not used, set it to NULL. If XF_MATCHID is specified, the applications conducting the transfer determine the meaning of the string.

lpDescription

The single, friendly name to describe a file transfer that involves multiple files. This name can be, for instance, "Budget Update" when transferring multiple files in a budget update. This parameter is optional, and if not used, set it to NULL.

lpFiles

Identifies the file or list of files to send. It contains successive, zero-terminated strings that are the filenames to transfer. The entire list of files ends with an additional zero; that is, two zeros terminate the final filename string. This parameter is optional, and if not used, set it to NULL.

lpTag

Contains optional, additional information to send to the receiving application. It can contain arbitrary, binary information for the receiving application to interpret, and it can be sent even if no file is sent. For example, it can convey the paragraph and sentence to where a receiving word processing application moves its cursor when displaying a transferred file.

dwTag

Length of the tag to send, in bytes.

dwFlags

Specifies conditions for the connection and send. It can be any of these values:

Value | Meaning
XF_DONT_COMPRESS | Don't compress files when transferring. If not specified, files are compressed for efficient transfer.
XF_INCLUDEPATH | Include path names along with filenames. If not specified, only filenames are sent.
XF_MATCHID | Allow only the specific application with the UUID in the uuidAppID field of the XFRADDRESS to receive the files.
XF_WAIT | Wait until the file transfer is complete before returning from the function call. If not specified, the function returns immediately.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

If the XF_WAIT flag is specified, the file transfer engine makes the connection and transfer before returning from the call. Otherwise, the call returns immediately, an XF_SUCCESS return value does not necessarily signify a successful operation, and the file transfer engine continues to make the connection and the transfer.

The xfConnectAndSend function call is equivalent to calling the xfConnect, xfSend, and xfDisconnect functions. If the complete list of files is known before making the connection, and if the xfConnect function call is not required, the xfConnectAndSend function can be used instead of the equivalent function sequence.

If no UUID is specified in the uuidAppID field fo XFRADDRESS, the default application receives the files. If a UUID is specified, the files will be received by the application or by the default application if the application is not available. If a UUID is specified and the XF_MATCHID option is used, the files must be received by the specific application or the transfer fails.

See Also

xfConnect, xfDisconnect, xfInitialize, XFRADDRESS, xfSend


xfDefNotifyProc

#include <fte.h>

DWORD WINAPI xfDefNotifyProc(hSession, hConnection, dwNotificationCode, dwParam)
HSESSION hSession; /* handle of session in which event occurred */
HCONNECTION hConnection; /* handle of connection in which event occurred */
DWORD dwNotificationCode; /* code specifying which event that occurred */
DWORD dwParam; /* parameter for notification code */

The xfDefNotifyProc function invokes the use of the default action in response to a notification event.

Parameters

hSession

Identifies the session provided by the xfNotifyProc routine.

hConnection

Identifies the connection provided by the xfNotifyProc routine.

dwNotificationCode

Identifies the file transfer event that occurred. See xfNotifyProc for possible values.

dwParam

Specifies a parameter for the notification event. See xfNotifyProc for possible values.

Return Value

Depends on the dwNotificationCode.

Comments

The file transfer engine calls the notification procedure when a file transfer event occurs. The notification procedure can execute application code to respond appropriately, or it can call the xfDefNotifyProc function to invoke the default action in response to the event.

For instance, the application is responsible for the user interface for file transfers, unless the notification procedure calls xfDefNotifyProc. Then the user interacts with the default file transfer interface.

See Also

xfNotifyProc, xfInitialize


xfDisconnect

#include <fte.h>

DWORD WINAPI xfDisconnect(hConnection, dwFlags)
HCONNECTION hConnection; /* handle of connection to close */
DWORD dwFlags; /* currently not used */

The xfDisconnect function immediately shuts down any pending transfers on the connection and then closes the connection.

Parameters

hConnection

Identifies the connection to close.

dwFlags

Currently not used. The value should be 0.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

The xfDisconnect function call terminates an xfConnect function call. It does an implicit xfAbortTransfer function call, if appropriate. The connection handle is invalid after the call.

See Also

xfAbortTransfer, xfConnect


xfGetStatusLong

#include <fte.h>

LONG WINAPI xfGetStatusLong( hConnection, nInfo)
HSESSION hSession; /* handle of session about which to get information */
HCONNECTION hConnection; /* handle of connection about which to get information */
int nInfo; /* integer representing type of information to get */

The xfGetStatusLong function gets numeric information about the file transfer session.

Parameters

hConnection

Specifies the connection about which to get information.

nInfo

Specifies the type of information to get. It can be one of these values:

Values | Meaning
XF_GSL_BYTESPERSECOND | Approximate rate of transfer.
XF_GSL_CURRENTINDEX | Index (1, 2, ... ) of current file.
XF_GSL_CURRENTPERCENTDONE | Percent of the transfer completed (0 through 100)
XF_GSL_CURRENTSIZE | Total bytes in current file to transfer.
XF_GSL_CURRENTTRANSFERRED | Bytes transferred of current file.
XF_GSL_ERROR | Current error code for the connection.
XF_GSL_NUMFILES | Number of files to transfer.
XF_GSL_SECONDS | Elapsed time of connection.
XF_GSL_TAG | Pointer to the tag.
XF_GSL_TAGSIZE | Size of the tag in bytes.
XF_GSL_TOTALPERCENTDONE | Percent of the entire transfer completed (0 through 100)
XF_GSL_TOTALSIZE | Total bytes in all files to transfer.
XF_GSL_TOTALTRANSFERRED | Bytes transferred of all files.
XF_GSL_TRANSFERSECONDS | Elapsed time of file transfer.
XF_GSL_UUID | Pointer to the UUID.

Return Value

The return value is the requested information.

See Also

xfGetStatusText, xfGetVersion.


xfGetStatusText

#include <fte.h>

DWORD WINAPI xfGetStatusText(hConnection, nInfo, lpText, cbMax)
HCONNECTION hConnection; /* handle of connection about which to get information */
int nInfo; /* specifies type of information to get */
LPSTR lpText; /* pointer to buffer that receives text (string) */
int cbMax; /* maximum size of string to fit in buffer */

The xfGetStatusText function gets text (string) information about the file transfer session.

Parameters

hConnection

Specifies the connection about which to get information.

nInfo

Specifies the type of information to get. It can be one of these values:

Value | Meaning
XF_GST_DESTFILENAME | Name of file being written.
XF_GST_FRIENDLYNAME | Optional name describing the group of files.
XF_GST_LOCALNAME | Name of the local user.
XF_GST_OPENNAME | Optional name of file to open after transfer is complete.
XF_GST_SOURCEFILENAME | Name of file being sent.
XF_GST_REMOTENAME | Name of the remote user.

lpText

Pointer to the buffer that receives the information.

cbMax

Maximum size (in bytes) of the buffer (including a null terminating character).

Return Value

The return value is the number of bytes, not including the terminating null character, in the returned character string. If there is a problem with the retrieval, the return value is 0:

See Also

xfGetStatusLong, xfGetVersion.


xfGetVersion

#include <fte.h>

DWORD WINAPI xfGetVersion(void)

The xfGetVersion function retrieves the current version of the file transfer engine.

Parameters

This function has no parameters.

Return Value

The return value specifies the major and minor version numbers of the file transfer engine.

Comments

The low-order word of the return value contains the version. The low-order byte contains the major version. The high-order byte contains the minor version (revision) number as a two-digit decimal number.

See Also

xfGetStatusLong, xfGetStatusText.


xfInitialize

#include <fte.h>

DWORD WINAPI xfInitialize(lphSession, dwVersion, lpAppID, NotifyProc, dwFlags)
LPHSESSION lphSession; /* pointer to handle of session that was initialized */
DWORD dwVersion; /* version of file transfer API used to build application */
LPCUUID lpAppID; /* pointer to application ID of application to use */
XFNOTIFYPROC lpfnNotifyProc; /* pointer to callback function for event handling */
DWORD dwFlags; /* specifies initialization options */

The xfInitialize function indicates that an application is ready to transfer files.

Parameters

lphSession

Identifies the session returned by the initialization call for use in subsequent calls involving the application ID.

dwVersion

Identifies the version of the file transfer API used to build the application.

lpAppID

Identifies an application ID that the calling application supports. The application ID should be previously registered for the calling application. If not specified, an error occurs.

lpfnNotifyProc

Identifies the routine to call when an event occurs that needs application action.

dwFlags

Specifies properties of the calling application. It has the following value:

Value | Meaning
XF_DEFAULT | Make the calling application the default file transfer application.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

Call xfInitialize before all other file transfer API calls other than xfGetVersion and xfRegister. If the calling application supports multiple application IDs, call xfInitialize to create a session for each of the supported application IDs.

Once a session is created for a specific application ID by calling the xfInitialize function, the session must be terminated with a call to the xfUninitialize function before calling the xfInitialize function again for the same application ID.

When building the calling application, use the value of the XF_VERSION constant from the FTE.H include file to set the value of dwVersion. This allows the file transfer engine to check for compatibility with the function calls of the calling application. If the calling application supports multiple versions of the file transfer engine, use the xfGetVersion function return value to determine the version of the engine. This allows the calling application to check for compatibility.

See Also

xfGetVersion, xfUninitialize, xfRegister, xfNotifyProc


XFNOTIFYPROC

#include <fte.h>

XFNOTIFYPROC xfNotifyProc(hSession, hConnection, dwNotificationCode, dwParam)
HSESSION hSession; /* handle of session in which event occurred */
HCONNECTION hConnection; /* handle of connection in which event occurred */
DWORD dwNotificationCode; /* code specifying which event occurred */
DWORD dwParam; /* parameter for notification code */

xfNotifyProc is an application-defined call-back function for file transfer events.

Parameters

hSession

Provides a session to the xfNotifyProc routine.

hConnection

Provides a connection to the xfNotifyProc routine.

dwNotificationCode

Specifies the file transfer event that occurred.

Value | Meaning
XFN_CONNECTION_ABORT | Connection abnormally terminating.
XFN_CONNECTION_END | Connection normally closing.
XFN_CONNECTION_START | Connection starting.
XFN_FILE_ABORT | File transfer abnormally terminating.
XFN_FILE_BLOCK | Transfer of one block of data complete.
XFN_FILE_END | File transfer normally closing.
XFN_FILE_START | File transfer starting.
XFN_TRANSFER_ABORT | Transfer abnormally terminating.
XFN_TRANSFER_ACCEPT | The receiver is notified that transfer is accepted. An application should call xfReceive to start receiving files.
XFN_TRANSFER_CONFIRMED | The sender is notified that the transfer is confirmed.
XFN_TRANSFER_DECLINE | The sender is notified that the transfer is declined.
XFN_TRANSFER_END | Transfer normally closing.
XFN_TRANSFER_START | Transfer starting.
XFN_TRANSFER_REFUSE | The receiver is notified that the current application declined the transfer.
XFN_UI_CONNECT | User interface connect notification. See dwParam for meaning.
XFN_UI_CONFIRMTRANSFER | Transfer about to start. Return 1 if transfer is OK, 0 if not. This is the point at which to prompt the user to confirm acceptance through a message box. xfDefNotifyProc will return 0 if the notification code is passed on to it.
XFN_UI_DISCONNECT | User interface disconnect notification. See dwParam for meaning.
XFN_UI_TRANSFER | User interface transfer notification. See dwParam for meaning.

dwParam

Specifies a parameter for event corresponding to dwNotificationCode.

  • For XFN_UI_CONNECT, XFN_UI_DISCONNECT, and XFN_UI_TRANSFER, dwparam specifies additional information and can be one of these values to describe the connect, disconnect, or transfer operation:
Value | Meaning
XF_UI_ERROR | Error occurred during operation. Application normally creates dialog here.
XF_UI_PROGRESS | Update progress of operation.
XF_UI_START | Started operation. Application normally creates dialog here. xfDefNotifyProc can create dialog.
XF_UI_STOP | Finished operation.

xfDefNotifyProc will create the progress dialog when it receives the XFN_UI_TRANSFER notification with a dwparam of XF_UI_START. It will update the progress indicator when it receives XF_UI_PROGRESS then it will close the dialog when it receives XF_UI_STOP.

Return Value

If the function does not handle the notification code, the value returned should be the value from xfDefNotifyProc. If the application handles all the user interface, it should not pass the XFN_UI notification codes to xfDefNotifyProc. Instead, it should return 0. When an XFN_UI_CONFIRM_TRANSFER is received, return 1 to accept the files and 0 to decline.

Comments

Pass this function to the xfInitialize function when a session is started. The file transfer engine calls the notification procedure when a file transfer event occurs. These events include ones associated with connections, transferring of files, and the user interface elements.

Applications should generally pass all notification codes on to xfDefNotifyProc. This routine should not block except when handling XF_UI_CONFIRMTRANSFER. This should instead prompt the user for acceptance of the transfer.

If an application wishes to handle its own user interface messages, it should handle all XFN_UI notification codes.

See Also

xfDefNotifyProc, xfInitialize, xfReceive


XFRADDRESS, LPXFRADDRESS

#include <fte.h>

XFRADDRESS xfrAddress; /* variable-length structure describing transfer address */
LPXFRADDRESS lpAddress; /* 32-bit pointer to transfer address structure */

Variables of types XFRADDRESS and LPXFRADDRESS specify a transfer address.

Parameters

xfrAddress

Structure that describes a transfer address.

typedef struct tagXFRADDRESS
{
DWORD dwSize;
DWORD dwType;
UUID uuidAppID;
union {
DWORD dwDeviceId;
char achAddress[1];
}
}XFRADDRESS;

dwSize

Total size (in bytes) of structure including the dwSize field.

dwType

Type of transport for file transfer. It can be one of these values:

Value | Meaning
XF_VOICEVIEW | VoiceView modem transport.
XF_DATAMODEM | Data modem transport.
XF_ISDN | ISDN transport.
XF_IR | Infrared transport.
XF_NETWORK | Network transport.
XF_SVD | Simultaneous voice and data transport.

uuidAppID

Specific application ID associated with transfer. NULL specifies the default file transfer application.

dwDeviceId

The permanent line ID associated with a TAPI device. A value of -1 will specify the default TAPI device. This field is required for VoiceView transports.

achAddress

Character string that represents the transport-specific address: phone number, socket address, etc. Use achAddress when using nonVoiceView transports.

lpAddress

32-bit pointer to the transfer address structure.

See Also

UUID, xfConnect, xfConnectAndSend


xfReceive

#include <fte.h>

DWORD WINAPI xfReceive(hConnection, lpDirectory, dwFlags)
HCONNECTION hConnection; /* handle of connection on which to receive */
LPCSTR lpDirectory; /* pointer to directory for received files */
DWORD dwFlags; /* currently not used */

The xfReceive function signals that the transfer should proceed.

Parameters

hConnection

Identifies the connection provided by the xfNotifyProc routine.

lpDirectory

Identifies the path for storage of the transferred files. If NULL, then use default path of the file transfer engine.

dwFlags

Currently not used. The value should be 0.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

An application calls the xfReceive function only in its xfNotifyProc routine when that routine receives an XFN_TRANSFER_ACCEPT request to receive files. The xfReceive call signals that the transfer should proceed, and it specifies the destination directory for the file transfers.

See Also

xfNotifyProc


xfRegister

#include <fte.h>

DWORD WINAPI xfRegister(lpAppID, lpFilename, dwFlags)
LPCUUID lpAppID; /* pointer to application ID of application to register */
LPCSTR lpFilename; /* pointer to application filename to register */
DWORD dwFlags; /* flag that specifies registration options */

The xfRegister function registers an application with the file transfer engine. It associates an application ID with the specific application. It also determines whether to autolaunch the application, and if it is capable of handling default file transfers.

Parameters

lpAppID

Identifies an application ID that the application supports.

lpFilename

Identifies the filename of the application that supports file transfers for the specified application ID. This field can be NULL if the application doesn't autolaunch.

dwFlags

Specifies the registration options for the application. It can be one or more of the following values:

Value | Meaning
XF_AUTOLAUNCH | Automatically launch, if necessary, the application filename when receiving a file for the application ID.
XF_DEFAULT | Establish the application filename as the default file transfer application.
XF_REGISTER | Register support for the application ID for the application filename (default).
XF_UNREGISTER | Remove support for the application ID by the application filename.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

Registration usually occurs when an application is installed. If registration specifies the XF_DEFAULT option, the application serves as the default file transfer application. That is, the application receives files for application IDs not registered with the engine and receives files for registered applications that don't autolaunch. The last application registered as the default file transfer application remains that until replaced. Therefore, some applications may register as the default file transfer application each time they are run to ensure their status as default.

If an application supports transfers for several application IDs, the application can be registered once for each supported application ID. However, only one application can be registered to receive files for a specific application ID.

An application may not be running at the time the engine receives a supported file. If the autolaunch option XF_AUTOLAUNCH is specified at registration, the engine automatically launches the application. If the autolaunch option is not specified, then the default file transfer application receives the file.

To change the registration options for an application, first call xfRegister with the XF_UNREGISTER option. Then call xfRegister with the logical or of the XF_REGISTER option and any new, desired options.

See Also

xfInitialize


xfSend

#include <fte.h>

DWORD WINAPI xfSend(hConnection, lpOpen, lpDescription, lpFiles, lpTag, dwTag, dwFlags)
HCONNECTION hConnection; /* handle of connection on which to send */
LPCSTR lpOpen; /* pointer to parameter for receiving application */
LPCSTR lpDescription; /* pointer to friendly description of transfer */
LPCSTR lpFiles; /* pointer to list of files to transfer */
LPCSTR lpTag; /* pointer to arbitrary data for receiving application */
DWORD dwTag; /* number of bytes in tag */
DWORD dwFlags; /* flag specifying send conditions */

The xfSend function starts a transfer of file(s) on the specified connection.

Parameters

hConnection

Identifies an existing connection on which to send.

lpOpen

Indicates the filename to open after the transfer is complete. This parameter is optional, and if not used, set it to NULL. If XF_MATCHID is specified, the applications conducting the transfer determine the meaning of the string.

lpDescription

The friendly name used to describe a file transfer. For instance, this can be "Budget Update" when transferring multiple files in a budget update. This parameter is optional, and should be set to NULL if not used.

lpFiles

Identifies the file or list of files to send. It contains successive, zero-terminated strings that are the filenames to transfer. The entire list of files ends with an additional zero; that is, two zeros terminate the final filename string. This parameter is optional and should be set to NULL if not used.

lpTag

Contains additional information to send to the receiving application. It can contain arbitrary, binary information for the receiving application to interpret, and it can be sent even if no file is sent. For example, it can convey the paragraph and sentence to where a receiving word processing application moves its cursor when displaying a transferred file.

dwTag

Length of the tag to send, in bytes.

dwFlags

Specifies conditions for the send. It can be any of these values:

Value | Meaning
XF_INCLUDEPATH | Include path names along with filenames. If not specified, only filenames are sent.
XF_WAIT | Wait until the file transfer is complete before returning from the function call. If not specified, return immediately after requesting the transfer.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

The xfConnect function must be called to open a connection before calling this function.

Once a connection is open, the xfSend function can be called once to transfer multiple files, or it can be called multiple times and transfer one or more files each time. This versatility is useful if the full list of files to transfer is not known at the time the connection is made.

If the complete list of files is known before making the connection, and if use of the xfConnect function call is not required, the xfConnectAndSend function can be used instead of successive xfConnect, xfSend, and xfDisconnect function calls.

See Also

xfConnect, xfConnectAndSend, xfGetStatusText, xfGetStatusLong


xfUninitialize

#include <fte.h>

DWORD WINAPI xfUninitialize(hSession, dwFlags)
HSESSION hSession; /* handle of existing session to uninitialize */
DWORD dwFlags; /* currently not used */

The xfUninitialize function indicates that an application no longer wants to transfer files..

Parameters

hSession

Identifies the existing session to shutdown. A previous call by the application to the xfInitialize function defines the session handle.

dwFlags

Currently not used. It should be 0.

Return Value

The return value specifies the result of the termination request. It can be any one of the values list in section 2.2.4. File Transfer Errors.

Comments

A call to the xfUninitialize function should occursfor each call to the xfInitialize functionThe session handle is invalid after the call.

See Also

xfInitialize, xfRegister


Chapter 4 Sockets API Guide

CHAPTER 4

Sockets API Guide

Windows Sockets provide a network applications programming interface based on the socket mechanism used by the Berkeley Software Distribution (BSD) of UNIX Ò. The Windows Sockets Version 1.1 specification defines the Windows-specific extensions to the standard BSD routines. VoiceView Sockets in turn provide an additional extension to Windows Sockets by including VoiceView-enabled hardware as communications devices.

This chapter describes the use of the extensions that VoiceView Sockets provide to Windows sockets. Chapter 5, "Sockets API Reference," includes details for different or extended items.


4.1 Characteristics of VoiceView Sockets

VoiceView Sockets, like sockets in general, provide communications between processes running on separate, but connected, computing systems. A socket is a bi-directional endpoint of communication. For VoiceView, the communications channel is the telephone network, and each endpoint includes a VoiceView-enabled hardware device. VoiceView Sockets differ from other typical sockets in two major ways: quality of service and method of addressing.

The quality of service for VoiceView Sockets is low, because the transfer of information is extremely slow compared to TCP/IP or IPX sockets. Additionally, although VoiceView optimizes the transition from voice to data modes, it interrupts the normal voice communication for at least one second. An application that switches frequently between voice and data modes can disrupt a normal voice call. The advantages that VoiceView provides should offset that disruption.

VoiceView Sockets addressing differs from typical sockets because it involves a point-to-point connection with a specific protocol ID embedded in the address structure. This necessitates that an application call the bind function before it can use the listen function.


4.2 Inside VoiceView Sockets

When using the VoiceView Sockets API, you need to keep in mind several unique features of that API. These features include the protocol ID and the muting control.


4.2.1 Protocol ID

VoiceView Sockets send information from an application on one computer to a corresponding application on another computer by specifying a protocol ID when setting up the connection. The specified protocol ID determines which application should receive the data.

A universal, unique identifier (UUID) identifies the specific protocol. The developer of an application assigns the UUID to that protocol (see the uuidProtocol field description of the sockaddr function in Chapter 5 for details on how to obtain and to use a UUID.)

Usually, only one application supports a specific UUID. However, if two or more applications inter-operate, they all must use the same UUID.


4.2.2 Muting Control

A VoiceView-enabled modem mutes the local telephone set when sending data. Muting occurs when the application calls the send or the sendto function or when the application receives notification from a remote modem to receive data. Muting stops when the data transmission is complete.

If an application knows that the remote application will immediately send back data, it can set the VV_REQUESTREPLY flag in the send or sendto function call. This causes the telephone sets to remain muted after the first transmission in preparation for the return transmission. Because the telephone line remains in data mode between transmissions, the time spent switching between voice and data is minimal. Voice communication resumes when all exchanges of data are complete.


4.3 Extensions with VoiceView Sockets

The VoiceView Sockets extend two areas of Windows sockets: data structures and functions. One data structure, sockaddr, includes additional information for VoiceView. Several of the individual API functions use this modified address structure. A few of the individual functions have limited capabilities.

See wsvv.h file for VoiceView specific extensions.


4.3.1 Socket Address Structure

The socket address structure is:

struct sockaddr_vv {
u_short sa_family;
u_short wFlags;
DWORD dwDeviceId;
UUID uuidProtocol;
};

sa_family

The value for the address format field is AF_VOICEVIEW.

uuidProtocol

16-byte universally unique identifier for the sockets protocol. It replaces the protocol parameter of the socket function.

wFlags

Reserved for future use. Its value should be 0.

dwDeviceId

Desired TAPI line device ID to use for subsequent calls. A value of -1 will specify the default TAPI device.

Note that this structure is different and slightly larger than the default sockets device.


4.3.2 Sockets Routines

These functions use the modified socket address structure:

  • accept
  • bind
  • connect
  • recvfrom
  • sendto

Pass the protocol, or return it, using the sockaddr structure in these functions.

These functions have modified capabilities with VoiceView:

Function | Modification
bind | Must call before calling listen.
getsockopt | Retrieves VoiceView transport information.
listen | Must call bind before calling.
send | Supports the additional value, VV_REQUESTREPLY, for the flags parameter. See send in Chapter 5.
sendto | Supports additional values, VV_QUERY and VV_REQUESTREPLY, for the flags parameter. See sendto in Chapter 5.
socket | Adds the AF_VOICEVIEW address format value for the af parameter. Supports SOCK_DGRAM, SOCK_STREAM, and SOCK_RAW socket types. Set the protocol parameter to 0 and use the uuidProtocol field of the sockaddr structure instead.


Chapter 5 Sockets API Reference

CHAPTER 5

Sockets API Reference

This chapter describes, in alphabetic order, addenda to standard items (structures and functions) of the Windows Sockets applications programming interface. Each description contains the syntax, purpose, and addendum for the item. Only items with addenda to the Windows Sockets Version 1.1 specification appear. Refer to that specification for additional details about the included items, as well as information about the unchanged items.

The syntax for each item appears in C-language format. In your C-language source files, spell the item names exactly as shown, and use parameters in the given order. You can use these items in your applications by placing the directive

#include <wsvv.h>

at the beginning of your source files.


accept

#include <wsvv.h>

SOCKET PASCAL FAR accept(s, addr, addrlen)
SOCKET s; /* socket listening for connections */
struct sockaddr FAR * addr; /* address structure for connecting entity */
int FAR * addrlen; /* length of address structure */

Accept a connection on a socket.

Addendum

The accept function receives address information about the connecting entity using the modified sockaddr structure.

See Also

bind, connect, listen, select, socket, WSAAsyncSelect


bind

#include <wsvv.h>

int PASCAL FAR bind(s, name, namelen)
SOCKET s; /* unbound socket to associate */
const struct sockaddr FAR * name; /* address structure assigned to socket */
int namelen; /* length of address structure */

Associate a local address with a socket.

Addendum

The bind function associates a protocol ID with a socket using the modified sockaddr structure.

An application must call the bind function before it calls the listen function.

See Also

connect, listen, getsockname, setsockopt, socket, WSACancelBlockingCall


connect

#include <wsvv.h>

int PASCAL FAR connect(s, name, namelen)
SOCKET s; /* unconnected socket to use */
const struct sockaddr FAR * name; /* address structure assigned to socket */
int namelen; /* length of address structure */

Establish a connection to a peer.

Addendum

The connect function specifies a protocol ID for a socket using the modified sockaddr structure.

See Also

accept, bind, getsockname, select, socket, WSAAsyncSelect


getsockopt

#include <wsvv.h>

int PASCAL FAR getsockopt(s, level, optname, optval, optlen)
SOCKET s; /* socket from which to retrieve option */
int level; /* level at which option is defined */
int optname; /* option to retrieve */
char FAR * optval; /* pointer to buffer to receive value */
int FAR * optlen; /* pointer to length of buffer */

Retrieve a socket option.

Addendum

Two options have been added. VVSO_MODE indicates the current mode: VVM_VOICE, VVM_SEND, or VVM_RECV. VVSO_BYTESPENDING indicates how many bytes are waiting in the queue to be sent.

See Also

setsockopt, socket, WSAAsyncSelect


listen

#include <wsvv.h>

int PASCAL FAR listen(s, backlog)
SOCKET s; /* bound, unconnected socket to listen on */
int backlog; /* size of queue for pending connections */

Establish a socket to listen for incoming connection.

Addendum

An application must call the bind function before it calls the listen function.

See Also

accept, bind, connect, socket


recvfrom

#include <wsvv.h>

int PASCAL FAR recvfrom(s, buf, len, flags, from, fromlen)
SOCKET s; /* bound socket to receive data */
char FAR * buf; /* buffer to receive incoming data */
int len; /* length of buffer */
int flags; /* specifies optional behavior of the call */
struct sockaddr FAR * from; /* address structure to receive source address */
int FAR * fromlen; /* length of address structure */

Receive a datagram and store the source address.

Addendum

The recvfrom function receives a protocol ID for a socket using the modified sockaddr structure.

See Also

recv, send, socket, WSAAsyncSelect


send

#include <wsvv.h>

int PASCAL FAR send(s, buf, len, flags)
SOCKET s; /* connected socket on which to send */
const char FAR * buf; /* buffer containing data to transmit */
int len; /* length of data in buffer */
int flags; /* specifies optional behavior of the call */

Send data on a connected socket.

Addendum

The additional value for the flags parameter is VV_REQUESTREPLY. It indicates that the receiver will return data. This allows minimization of muting time of voice communications.

See Also

recv, recvfrom, socket, sendto, WSAStartup


sendto

#include <wsvv.h>

int PASCAL FAR sendto(s, buf, len, flags, to, tolen)
SOCKET s; /* connected socket on which to send */
const char FAR * buf; /* buffer containing data to transmit */
int len; /* length of data in buffer */
int flags; /* specifies optional behavior of the call */
const struct sockaddr FAR * to; /* address structure for destination socket */
int tolen; /* length of address structure */

Send data to a specific destination.

Addendum

The sendto function specifies the protocol ID for the socket using the modified sockaddr structure.

The additional value for the flags parameter is VV_REQUESTREPLY. It indicates that the receiver will return data. This allows minimization of muting time of voice communications.Additional values for the flags parameter are:

See Also

recv, recvfrom, socket, sendto, WSAStartup


sockaddr

#include <wsvv.h>

struct sockaddr_vv {
u_short sa_family; /* socket address format */
u_short wFlags; /* specifies optional behavior on a connection */
DWORD dwDeviceId; /* TAPI device ID to use for connections */
UUID uuidProtocol; /* socket protocol */
};

Socket address structure.

Addendum

Instead of using the protocol parameter of the socket function call, set that parameter to 0 and use the uuidProtocol field of the sockaddr structure. Pass the protocol, or return it , using that structure in the accept, bind, connect, , and sendto functions. Also, an application must call the bind function to specify the protocol before it calls the listen function.

The modified sockaddr structure has these fields:

sa_family

The value for the address format field is AF_VOICEVIEW.

wFlags

Reserved for future use. Its value should be 0.

dwDeviceId

Desired TAPI line device ID to use for subsequent calls.

uuidProtocol

16-byte universally unique identifier for the sockets protocol. It replaces the protocol parameter of the socket function.

To produce an application ID, use the EXTIDGEN.EXE or GUUIDGEN.EXE applications. Consult the release notes for the Microsoft Windows SDK for an alternative version. These applications generate a value that is guaranteed to be unique.

See Also

accept, bind, connect, getpeername, getsockname, recvfrom, sendto, socket


socket

#include <wsvv.h>

SOCKET PASCAL FAR socket(af, type, protocol)
int af; /* address format specification */
int type; /* type specification for new socket */
int protocol; /* not supported */

Create a socket.

Addendum

For af, the address format specification, AF_VOICEVIEW is available.

Sockets support SOCK_DGRAM, SOCK_STREAM, and SOCK_RAW for type, the type specification.

Use the uuidProtocol field of the sockaddr structure to convey the socket protocol. Set the protocol parameter to 0, or don't specify one. The protocol parameter is ignored.

See Also

accept, bind, connect, getpeername, getsockname, getsockopt, listen, recvfrom, select, send, sendto, setsockopt, sockaddr, WSAAsyncSelect