Sapphire Solutions Ltd - Utility Manuals

Manual Options

Please select which version of the manual you wish to view:

  • Online Manual
  • Download web pages as Zip file (511 Kb)
  • Download Windows CHM Manual file (775 Kb)
Copyright © 2001 - 2004, Sapphire Solutions Ltd


Installing a Utility
eVB Users

To install the utility for use with eMbedded Visual Basic, the associated DLL needs to be copied to the \Windows directory of your target device. The correct DLL will be located under the directory that relates to your target device within the demo download or licensed download. Simply use ActiveSync or equivalent to copy the DLL to your target device. Please ensure that your client PC has been configured to show .DLL files.

VB.NET Users

To install the utility for use with VB.NET, the associated DLL needs to be copied to the application directory of your target device. The correct DLL will be located under the directory that related to your target device within the demo download or licensed download. Simply use ActiveSync or equivalent to copy the DLL to your target device. Please ensure that your client PC has been configured to show .DLL files.

Emulator Installations

If you plan to use an emulator version of the DLL, you still need to follow the specific instructions depending on whether you are using eVB or VB.NET. To get the DLL on the emulator will differ depending on the emulator device you are using.

Direct Copy
Some emulators allow you to access the emulator's file system right through Windows Explorer. Simply locate the directory and copy the emulator DLL into the correct path.

eVB File Viewer
Using the File Viewer under Remote Tools in eMbedded Visual Basic, you can upload the DLL to the emulator device.

Attach to VB.NET Project
VB.NET allows you to attach the DLL to the project and it will send the DLL to the client emulator device when you deploy the project. Since VB.NET requires the DLL to be in the application path, the DLL will be copied to the same location as the program's .exe.


Sapphire RAS Utility

Sapphire RAS Utility Contents

The Sapphire RAS Utility is designed for dialing and terminating remote connections along with full phone book management. This document is for version 9.30 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire RAS Utility is designed for eVB and VB.NET developers allowing an application to dial and hang-up any selected connection and management of connection entries. The utility is capable of doing the following:

  • Dial a connection
  • Hang-up a connection
  • Retrieve connection login defaults
  • Store connection login defaults
  • Capture an existing connection
  • Retrieve a connection list
  • Connection status reporting
  • Error handling
  • Retrieval of a connection entry
  • Modify an existing connection entry
  • Rename a connection entry
  • Remove a connection entry
  • Set country code
  • Set area code
  • Set baud rate, data bits, parity, etc
  • Set IP address details
  • Set dialing location settings
  • Fully compatible with VB.NET

Version History

v9.3 | Support for GPRS phone book entries Asynchronous connection method for less complex implementation code Setting the default phone book entry
v9.0 | VB.NET Compatible Added retrieving and storing the Work/Internet dial-up setting: sPBGetWorkInternet, sPBSetWorkInternet


Supported Hardware

The current supported hardware for the Sapphire RAS Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HDT600-SH4
  • HPC Pro2.11-ARM
  • HPC Pro2.11-MIPS
  • HPC Pro2.11-SH3
  • HPC Pro2.11-SH4
  • HPC Pro2.11-X86-Emulator
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Palm Size PC 2.11-MIPS
  • Palm Size PC 2.11-SH3
  • Palm Size PC 2.11-X86-Emulator
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire RAS Utility comes with a demo project that shows how to dial and terminate a connection along with full management of the devices phone book. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

Main Application Screen
Ras Menu Screen
Dial and Hang-Up Screen
Dial-Up Connection Settings
Phone Book Settings
Phone Book Settings GPRS
Advanced Phone Book Settings
Location Settings


Main Application Screen
When the RAS and FTP demo runs, you will see the main application screen. Depending on which utility you have installed, the RAS and/or FTP options will become active.

Use the Close button to exit the demo.


RAS Menu Screen

This menu gives the options for the RAS specific functionality.

RAS Dial & Hang Up
This allows you to initiate or terminate a RAS connection.

Dial Up Settings
This allows you to configure your dial-up settings such as the phone book connection to use and the account username and password.

Phone Book Settings
This allows you to add, edit or remove connection entries in the device's phone book.

Phone Book Settings GPRS
This allows you to configure a GPRS connection into the phone book.

Location Settings
This allows you to configure the dialing locations for both the Work and Home profiles.

The Back button takes returns to the main application screen.


Dial and Hang-Up Screen

This screen gives you the option to connect synchronously or asynchronously. Connecting in synchronous mode will result in the DLL returning control back to the eVB application upon completion or fail. Connecting in asynchronous mode will allow the eVB application to monitor the dial progress.

This screen allows you to initiate and terminate a connection. If there is already a connection made when the screen loads, the application will retrieve the details of the connection and display them under the status.

Pressing the Dial Up button will start a connection based on the one selected in the Dial Up Settings screen.

Pressing the Hang Up button will terminate the current connection.

Pressing the Back button will return to the RAS Menu.


Dial-Up Connection Settings

The dial-up settings screen allows you to select the connection that you wish to connect to along with specifying various details about the connection account.

Name refers to the connection to connect to.
Username is the account username.
Password is the account password to use.
Domain is the account domain used when connecting.
My Network card connect to refers to the connection location to use. This will select the correct dialing patters specified in the location settings.
User/Pass Required specified whether to use the specified username and password or whether the server accepts anonymous connection (e.g. ActiveSync).

Set as Defaults
This will store the details that you have supplied so that any changes will be permanent.

Apply
This will keep any changes until the application has been closed or the list has been refreshed.

Back
This will return to the RAS menu screen.


Phone Book Settings

The phone book settings menu will allow you to configure the connection settings.

Name refers to the connection to modify.
Country Code is the telephone code of the country used when making an international call.
Area Code is the telephone code to use when making a national call.
Number is the telephone number of the connection.
Device is the hardware or port to use for the connection.
Type specifies the type of connection.

New Entry
This will clear the fields allowing for a new connection to be created.

Advanceds
This goes to the advanced settings for the connection.

Delete Entry
This removes an entry after a user confirmation.

Rename entry
This will the current phone book entry to be renamed.

Back
This will return to the RAS menu.

Save Entry
This will store any changes to the phone book.


GPRS Phone Book Settings

GPRS Connection Settings

The GPRS connection settings screen allows you to add a GPRS connection into the phone book.

The location settings screen allows you to set the current location setting for the RAS Demo and also create new locations and edit and delete existing ones.

Name refers to the phone book entry name.
Domain is the account domain used when connecting.
Device is the device to use to connect with.
Type is the type of connection to make.

Save Entry
This allows you to save changes to an existing location or a new entry.

Back
This returns to the RAS menu.


Advanced Phone Book Settings

This screen allows you to specify the advanced settings for the selected connection.

Simply modify the settings and select the next button to go to the next advanced screen or the back button to return to the phone book settings.

The next advanced settings screen allows you to specify the IP address of the device when the connection has been made. This can be server assigned using DHCP or a static address using the specific IP address field.

You can also specify whether to use Slip, software compression and IP header compression.

The back button returns to the previous phone book settings screen. The next button continues to the next screen for advanced settings.

The next screen allows you to configure the DNS and Wins servers.

You can either allow the server to automatically set the servers or you can manually specify them.

The first IP address is for the DNS server.

The second IP address is for the Alternative DNS Server.

The third IP address if for the WINS server.

The fourth IP address is for the Alternative Wins server.

The back button returns to the previous phone book settings screen.

The next button continues to the next screen for advanced settings.

The next screen allows you to configure the timeouts, modem commands and vaious other dialing options.

The back button returns to the previous phone book settings screen.

The next button returns to the phone book settings screen.


Location Settings

The location settings screen allows you to set the current location setting for the RAS Demo and also create new locations and edit and delete existing ones.

Name refers to the location name.
Local Calls refers to the connection string to use for local calls.
Long Distance refers to the connection string to use for long distance calls.
International refers to the connection string to use for international calls.
Country refers to the country code for this particular location.
Area refers to the area code for this particular location.

Set as Current
This sets the displayed location to the current location on the device.

New Entry
This clears the screen ready for a new location entry.

Delete Entry
This allows you to delete non-system entries.

Save Entry
This allows you to save changes to an existing location or a new entry.

Back
This returns to the RAS menu.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sRASDial | Initiate a remote connection in asynchronous mode
sRASDialOnly | Initiate a remote connection in synchronous mode
sRASGetParams | Retrieve stored username, password and domain from a specified connection
sRASSetParams | Set the username, password and domain for the specified connection
sRASHangUp | Terminate a connection
sRASCurrentConn | Retrieve the handle to an existing connection on the device
sRASStatus | Get the status of the connection
sRASStatusMsg | Get a text version of a connection status
sRASErrMsg | Get a text version of an error number
sPBGet | Retrieve a phone book entry
sPBSet | Set a phone book entry
sPBValidate | Validate a connection entry name
sPBDelete | Delete a connection entry
sPBRename | Rename a connection entry
sPBNames | Return a list of connection entry names that exist in the phone book
sPBDevices | Return a list of available connection devices
sPBGetWorkInternet | Retrieves the current work or Internet dial-up setting
sPBSetWorkInternet | Sets the dial-up work or Internet setting
sPBSetDefault | Sets the specified phone book entry as default
sLOCGetCurrent | Return a number references the current dialing location
sLOCSetCurrent | Set the current dialing location
sLOCGetNumber | Retrieve the number of dialing locations
sLOCSetNumber | Set the current location dialing number
sLOCGetLocation | Retrieve the details of a specified dialing location
sLOCSetLocation | Set the dialing location properties
sLOCDeleteLocation | Delete a dialing location


sRASDial

RAS Function Reference

sRASDial

RAS Function Reference

This function initiates a remote connection in asynchronous mode.

<DllImport("SapphireRAS.dll")> _
Public Function sRASDial(ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String, ByRef hRasConn As Integer, ByRef hDC As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry to dial.
sUsername
 | A string specifying the username for the remote connection.
sPassword
 | A string specifying the password for the remote connection.
sDomain
 | A string specifying the domain for the remote connection.
hRasConn
 | An integer variable that will store a handle to the remote connection.
hDC
 | A handle to the application form that is making the connection.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASDialOnly

RAS Function Reference

sRASDialOnly

RAS Function Reference

This function initiates a remote connection in synchronous mode.

<DllImport("SapphireRAS.dll")> _
Public Function sRASDial(ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String, ByRef hRasConn As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry to dial.
sUsername
 | A string specifying the username for the remote connection.
sPassword
 | A string specifying the password for the remote connection.
sDomain
 | A string specifying the domain for the remote connection.
hRasConn
 | An integer variable that will store a handle to the remote connection.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASGetParams

RAS Function Reference

sRASGetParams

RAS Function Reference

This function retrieves the stored username, password and domain fror the specified connection.

<DllImport("SapphireRAS.dll")> _
Public Function sRASGetParams(ByVal sEntryName As String, ByVal sRASNames As String) As Integer
End Function

Parameters

sEntryName
 | A string specifying the connection entry name.
sRASNames
 | A string variable used to store the details for the connection. It will store the username, password and domain separated by a bar (|) character. If the phone book was not found the function returns a string stating 'No Phone Book Entry'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASSetParams

RAS Function Reference

sRASSetParams

RAS Function Reference

This function sets the username, password and domain fror the specified connection.

<DllImport("SapphireRAS.dll")> _
Public Function sRASSetParams(ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String) As Integer
End Function

Parameters

sEntryName
 | A string specifying the existing connection entry name.
sUsername
 | A string specifying the username.
sPassword
 | A string specifying the password.
sDomain
 | A string specifying the domain.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASHangUp

RAS Function Reference

sRASHangUp

RAS Function Reference

This function disconnects a connection session.

<DllImport("SapphireRAS.dll")> _
Public Function sRASHangUp(ByVal hRasConn As Integer) As Integer
End Function

Parameters

hRasConn
An integer variable referencing the handle to the remote connection.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASCurrentConn

RAS Function Reference

sRASCurrentConn

RAS Function Reference

This function retrieves the name and handle to the current connection on the device.

<DllImport("SapphireRAS.dll")> _
Public Function sRASCurrentConn(ByRef hRasConn As Integer, ByVal sConnName As String) As Integer
End Function

Parameters

hRasConn
 | An integer variable used to store a handle to the current connection.
sConnName
 | A string variable used to store the name of the current connection.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASStatus

RAS Function Reference

sRASStatus

RAS Function Reference

This function retrieves the current status of the connection.

<DllImport("SapphireRAS.dll")> _
Public Function sRASStatus(ByVal hRasConn As Integer) As Integer
End Function

Parameters

hRasConn
An integer variable referencing the handle to the active connection.

Return Values

Returns a number indicating the connection's current state. A value of zero indicates that there is currently no connection initiated. A value of 25 indicates that the connection was lost during the dialing and authentication phase. A value of 1 indicates that the connection was successfully established. Use sRASStatusMsg to get a string version of the connection status.

Status Message Values

Error Number | Message Returned by sRASStatusMsg
0 | Not Connected
1 | Connected
2 | Opening Port
3 | Port Opened
4 | Connecting Device
5 | Device Connected
6 | All Devices Connected
7 | Authenticating
8 | Authenticating
9 | Retrying Authenticating
10 | Requesting Callback Number
11 | Requesting Password Change
12 | Starting Projection Phase
13 | Starting Link-Speed Calculation
14 | Authentication Has Been Acknowledged
15 | Starting Reauthentication
16 | Authentication Successful
17 | Disconnecting For Callback
18 | Resetting Modem
19 | Waiting For Incomming Call
20 | Completed Projection Phase
21 | Terminal State Set
22 | Retry Authentication State Set
23 | Callback State Set
24 | Change Password State Set
25 | Lost Connection
Other | Unknown Message


sRASStatusMsg

RAS Function Reference

sRASStatusMsg

RAS Function Reference

This function retrieves a string value of the specified status number.

<DllImport("SapphireRAS.dll")> _
Public Sub sRASStatusMsg(ByVal sStatusText As String, ByVal lStatus As Integer)
End Sub

Parameters

sStatusText
 | A string variable used to store the text description of the status. If the status number was not recognised the value will be 'Unknown Message status_number' where status_number represents the number that the function was called with.
lStatus
 | An integer value specifiying the status number to lookup.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.

Status Message Values

Error Number | Message Returned by sRASStatusMsg
0 | Not Connected
1 | Connected
2 | Opening Port
3 | Port Opened
4 | Connecting Device
5 | Device Connected
6 | All Devices Connected
7 | Authenticating
8 | Authenticating
9 | Retrying Authenticating
10 | Requesting Callback Number
11 | Requesting Password Change
12 | Starting Projection Phase
13 | Starting Link-Speed Calculation
14 | Authentication Has Been Acknowledged
15 | Starting Reauthentication
16 | Authentication Successful
17 | Disconnecting For Callback
18 | Resetting Modem
19 | Waiting For Incomming Call
20 | Completed Projection Phase
21 | Terminal State Set
22 | Retry Authentication State Set
23 | Callback State Set
24 | Change Password State Set
25 | Lost Connection
Other | Unknown Message


sRASErrMsg

RAS Function Reference

sRASErrMsg

RAS Function Reference

This function retrieves a string value of the specified error number.

<DllImport("SapphireRAS.dll")> _
Public Sub sRASErrMsg(ByVal sErrorText As String, ByVal lError As Integer)
End Sub

Parameters

sErrorText
 | A string variable used to store the text description of the error. If the error number was not recognised the value will be 'Undefined Error'.
lStatus
 | An integer value specifiying the error number to lookup.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.

Error Message Values

Error Number | Message Returned by sRASErrMsg
123 | Phone Book Entry Invalid Name
183 | Phone Book Entry Already Exists
601 | Invalid Port Handle
602 | Port Already Open
603 | Buffer Too Small
604 | Wrong Info Specified
605 | Cannot Set Port Info
606 | Port Not Connected
607 | Event Invalid
608 | Device Does Not Exist
609 | Device Type Does Not Exist
610 | Buffer Invalid
611 | Route Not Available
612 | Route Not Allocated
613 | Invalid Compression Specified
614 | Out Of Buffers
615 | Port Not Found
616 | Async Request Pending
617 | Already Disconnecting
618 | Port Not Open
619 | Port Disconnected
620 | No End Points
621 | Can Not Open Phone Book
622 | Can Not Load Phone Book
623 | Can Not Find Phone Book Entry
624 | Can Not Write Phone Book
625 | Corrupt Phone Book
626 | Cannot Load String
627 | Key Not Found
628 | Disconnection
629 | Remote Disconnection
630 | Hardware Failure
631 | User Disconnection
632 | Invalid Size
633 | Port Not Available
634 | Can Not Project Client
635 | Unknown
636 | Wrong Device Attached
637 | Bad String
638 | Request Timeout
639 | Can Not Get Lana
640 | Net Bios Error
641 | Server Out Of Resources
642 | Name Exists On Net
643 | Server General Net Failure
644 | Alias Not Added
645 | Auth Internal
646 | Restricted Logon Hours
647 | Acct Disabled
648 | Password Expired
649 | No Dialing Permission
650 | Server Not Responding
651 | From Device
652 | Unrecognised Response
653 | Macro Not Found
654 | Macro Not Defined
655 | Message Macro Not Found
656 | Default Off Macro Not Found
657 | File Could Not Be Opened
658 | Device Name Too Long
659 | Device Name Not Found
660 | No Responses
661 | No Command Found
662 | Wrong Key Specified
663 | Unknown Device Type
664 | Allocating Memory
665 | Port Not Configured
666 | Device Not Ready
667 | Reading Ini File
668 | No Connection
669 | Bad Usage In Ini File
670 | Reading Section Name
671 | Reading Device Type
672 | Reading Device Name
673 | Reading Usage
674 | Reading Max Connection BPS
675 | Reading Max Carrier BPS
676 | Line Busy
677 | Voice Answer
678 | No Answer
679 | No Carrier
680 | No Dial Tone
681 | In Command
682 | Writing Section Name
683 | Writing Device Type
684 | Writing Device Name
685 | Writing Max Connection BPS
686 | Writing Max Carrier BPS
687 | Writing Usage
688 | Writing Default Off
689 | Reading Default Off
690 | Empty Ini File
691 | Authentication Failure
692 | Port Or Device
693 | Not Binary Macro
694 | DCB Not Found
695 | State Machines Not Started
696 | State Machines Already Started
697 | Partial Response Looping
698 | Unknown Response Key
699 | Receive Buffer Full
700 | Command Too Long
701 | Unsupported BPS
702 | Unexpected Response
703 | Interactive Mode
704 | Bad Callback Number
705 | Invalid Auth State
706 | Writing Init BPS
707 | X25 Diagnostic
708 | Account Expired
709 | Changing Password
710 | Overrun
711 | RAS Manager Can Not Initialise
712 | Biplex Port Not Available
713 | No Active ISDN Lines
714 | No ISDN Channels Available
715 | Too Many Line Errors
716 | IP Configuration
717 | No IP Addresses
718 | PPP Timeout
719 | PPP Remote Terminated
720 | PPP No Protocols Configured
721 | PPP No Response
722 | PPP Invalid Packet
723 | Phone Number Too Long
724 | IPXCP No Dial Out Configured
725 | IPXCP No Dialing Configured
726 | IPXCP Dial Out Already Active
727 | Accessing TCPCFGDLL
728 | No IP RAS Adapter
729 | SLIP Requires IP
730 | Projection Not Complete
731 | Protocol Not Configured
732 | PPP Not Configured
733 | PPP CP Rejected
734 | PPP LCP Terminated
735 | PPP Required Address Rejected
736 | PPP NCP Terminated
737 | PPP Loopback Detected
738 | PPP No Address Assigned
739 | Can Not Use Logon Credentials
740 | TAPI Configuration
741 | No Local Encryption
742 | No Remote Encryption
743 | Remote Requires Encryption
744 | IPXCP Net Number Conflict
745 | Invalid SMM
746 | SMM Uninitialized
747 | No MAC For Port
748 | SMM Timeout
749 | Bad Phone Number
750 | Wrong Module
751 | PPP MAC
752 | PPP LCP
753 | PPP Auth
754 | PPP NCP
755 | Power Off
756 | Power Off CD
Other | Undefined Error


sPBGet

RAS Function Reference

sPBGet

RAS Function Reference

This function retrieves the specified phone book properties.

<DllImport("SapphireRAS.dll")> _
Public Function sPBGet(ByVal sEntryName As String, ByVal sPBData As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
sPBData
 | A string variable used to store the phone book properties into separated by a bar (|) character. If the phone book was not found the value will be 'No Such Phone Book Entry'. If the operation failed the function returns a string stating 'Problem Retrieving Phone Book Entry'.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBSet

RAS Function Reference

sPBSet

RAS Function Reference

This function sets the phone book properties.

<DllImport("SapphireRAS.dll")> _
Public Function sPBSet(ByVal sEntryName As String, _
ByVal sNumbers As String, ByVal sExtraInfo As String, ByVal sSettings As String, _
ByVal lPBBefore As Integer, ByVal lPBAfter As Integer, _
ByVal lPBManually As Integer, ByVal lPBWait As Integer, _
ByVal lbUseCountryAndAreaCodes As Integer, ByVal lDialAsLocalCall As Integer, _
ByVal lSpecificIpAddr As Integer, ByVal sIPAddress As String, _
ByVal lSpecificNameServers As Integer, ByVal sIPAddresses As String, _
ByVal lIpHeaderCompression As Integer, ByVal lSwCompression As Integer, _
ByVal lSlip As Integer, ByVal lGPRS As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
sNumbers
 | A string comprising of the country code, area code, local phone number, device name and device type separated by the tilder (~) character.
sExtraInfo
 | A string comprising of the flow control, credit card tone timeout, extra dialing command string and connection manager name (PPC2002 only) separated by the tilder (~) character.
sSettings
 | A string comprising of the dial-up timeout, baud rate, data bits, parity and stop bits separated by the tilder (~) character.
lPBBefore
 | An integer specifying the use terminal before connecting parameter. 1 = yes, 0 = no.
lPBAfter
 | An integer variable specifying the use terminal after connection parameter. 1 = yes, 0 = no.
lPBManually
 | An integer specifying the enter dialing commands manually parameter. 1 = yes, 0 = no.
lPBWait
 | An integer specifying the wait for dial tone before dialing. 1 = yes, 0 = no.
lUseCountryAndAreaCodes
 | An integer specifying the user country and area codes parameter. 1 = yes, 0 = no.
lDialAsLocalCall
 | An integer specifying the dial as local call parameter. 1 = yes, 0 = no.
lSpecificIpAddr
 | An integer specifying the use specific IP address parameter. 1 = yes, 0 = no.
sIPAddress
 | A string specifying the IP address to use with each element of the address separated by the tilder (~) character.
lSpecificNameServers
 | An integer specifying the use specific server address parameter. 1 = yes, 0 = no.
sIPAddresses
 | A string specifying the IP address of the DNS server, alternative DNS server, WINS server and alternative WINS server. Each element address and each element of each address is separated by the tilder (~) character.
lIpHeaderCompression
 | An integer specifying whether to use header compression. 1 = yes, 0 = no.
lSwCompression
 | An integer specifying whether to use software compression. 1 = yes, 0 = no.
lSlip
 | An integer specifying whether to use slip. 1 = yes, 0 = no.
lGPRS
 | An integer specifying whether the connection is a GPRS connection. 1 = yes, 0 = no.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBValidate

RAS Function Reference

sPBValidate

RAS Function Reference

This function checks if the specified connection entry name is in a valid format.

<DllImport("SapphireRAS.dll")> _
Public Function sPBValidate(ByVal sEntryName As String) As Integer
End Function

Parameters

sEntryName
A string specifying the name of the phone book entry.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBDelete

RAS Function Reference

sPBDelete

RAS Function Reference

This function deletes a connection entry from the connection manager.

<DllImport("SapphireRAS.dll")> _
Public Function sPBDelete(ByVal sEntryName As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBRename

RAS Function Reference

sPBRename

RAS Function Reference

This function renames a connection entry.

<DllImport("SapphireRAS.dll")> _
Public Function sPBRename(ByVal sOldEntryName As String, ByVal sNewEntryName As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sOldEntryName
 | A string specifying the name of the phone book entry to rename.
sNewEntryName
 | A string specifying the name to rename the connection entry to.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBNames

RAS Function Reference

sPBNames

RAS Function Reference

This function returns a list of connection entries that exist in the phone book.

<DllImport("SapphireRAS.dll")> _
Public Function sPBNames(ByRef lEntries As Integer, ByVal sRASNames As String) As Integer
End Function

Parameters

lEntries
 | An integer variable used to store the number of phone book entries returned
sRASNames
 | A string variable used to store the list of entry names separated by the bar (|) character. If there are no connection entries the value will be 'No Phone Book Entries'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBDevices

RAS Function Reference

sPBDevices

RAS Function Reference

This function returns a list of devices.

<DllImport("SapphireRAS.dll")> _
Public Function sPBDevices(ByRef lEntries As Integer, ByVal sRASNames As String) As Integer
End Function

Parameters

lEntries
 | An integer variable used to store the number of devices entries returned
sDevices
 | A string variable used to store the list of devices separated by the bar (|) character. If there are no devices the value will be 'No Device Names'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBGetWorkInternet

RAS Function Reference

sPBGetWorkInternet

RAS Function Reference

This function identifies whether the device is currently set for work or Internet dial-up.

<DllImport("SapphireRAS.dll")> _
Public Function sPBGetWorkInternet() As Integer
End Function

Parameters

None

Return Values

Returns 1 if it is configured for work, or 2 if it is configured for the Internet.


sPBSetWorkInternet

RAS Function Reference

sPBSetWorkInternet

RAS Function Reference

This function sets the devices work or Internet dial-up settings.

<DllImport("SapphireRAS.dll")> _
Public Function sPBSetWorkInternet(ByVal lNumber As Integer) As Integer
End Function

Parameters

lNumber
An integer specifying the work or Internet option. 1 = Work, 2 = Internet.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBSetDefault

RAS Function Reference

sPBSetDefault

RAS Function Reference

This function ets the specified phone book entry as default

<DllImport("SapphireRAS.dll")> _
Public Function sPBSetDefault(ByVal sEntryName As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sEntryName
 | A string specifying the name of the phone book entry to set as default.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetCurrent

RAS Function Reference

sLOCGetCurrent

RAS Function Reference

This function returns a number referencing the current dialing location.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCGetCurrent() As Integer
End Function

Parameters

None

Return Values

Returns a number referencing the current dialing location.


sLOCSetLocation

RAS Function Reference

sLOCSetLocation

RAS Function Reference

This function sets the location properties.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCSetLocation(ByVal lNumber As Integer, ByVal sSettings As String) As Integer
End Function

Parameters

lNumber
 | An integer number representing the location to set the details for.
sSettings
 | A string comprised of the location name, local calls, long distance, international, area code, call waiting, country code and dialing tone (0 = tone, 1 = pulse) separated by the bar (|) character.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetNumber

RAS Function Reference

sLOCGetNumber

RAS Function Reference

This function gets the number of available locations.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCGetNumber() As Integer
End Function

Parameters

None

Return Values

Returns the number of available locations.


sLOCSetNumber

RAS Function Reference

sLOCSetNumber

RAS Function Reference

This function sets the current location dialing number.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCSetNumber(ByVal lNumber As Integer) As Integer
End Function

Parameters

lNumber
An integer number representing the location dialing number.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetLocation

RAS Function Reference

sLOCGetLocation

RAS Function Reference

This function retrieves a specified location details.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCGetLocation(ByVal lNumber As Integer, ByVal sLocations As String) As Integer
End Function

Parameters

lNumber
 | An integer number representing the location to retrieve the details from.
sLocations
 | A string variable used to store the list of location properties separated by the bar (|) character.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCSetCurrent

RAS Function Reference

sLOCSetCurrent

RAS Function Reference

This function sets the current dialing location.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCSetCurrent(ByVal lNumber As Integer) As Integer
End Function

Parameters

lNumber
An integer referencing the dialing location to set as the current.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCDeleteLocation

RAS Function Reference

sLOCDeleteLocation

RAS Function Reference

This function deletes a dialing location.

<DllImport("SapphireRAS.dll")> _
Public Function sLOCDeleteLocation(ByVal lNumber As Integer) As Integer
End Function

Parameters

lNumber
An integer number representing the location to delete.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sRASDial | Initiate a remote connection in asynchronous mode
sRASDialOnly | Initiate a remote connection in synchronous mode
sRASGetParams | Retrieve stored username, password and domain from a specified connection
sRASSetParams | Set the username, password and domain for the specified connection
sRASHangUp | Terminate a connection
sRASCurrentConn | Retrieve the handle to an existing connection on the device
sRASStatus | Get the status of the connection
sRASStatusMsg | Get a text version of a connection status
sRASErrMsg | Get a text version of an error number
sPBGet | Retrieve a phone book entry
sPBSet | Set a phone book entry
sPBValidate | Validate a connection entry name
sPBDelete | Delete a connection entry
sPBRename | Rename a connection entry
sPBNames | Return a list of connection entry names that exist in the phone book
sPBDevices | Return a list of available connection devices
sPBGetWorkInternet | Retrieves the current work or Internet dial-up setting
sPBSetWorkInternet | Sets the dial-up work or Internet setting
sPBSetDefault | Sets the specified phone book entry as default
sLOCGetCurrent | Return a number references the current dialing location
sLOCSetCurrent | Set the current dialing location
sLOCGetNumber | Retrieve the number of dialing locations
sLOCSetNumber | Set the current location dialing number
sLOCGetLocation | Retrieve the details of a specified dialing location
sLOCSetLocation | Set the dialing location properties
sLOCDeleteLocation | Delete a dialing location


sRASDial

RAS Function Reference

sRASDial

RAS Function Reference

This function initiates a remote connection in asynchronous mode.

Declare Function sRASDial Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String, hRasConn As Long, hDC As Long, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry to dial.
sUsername
 | A string specifying the username for the remote connection.
sPassword
 | A string specifying the password for the remote connection.
sDomain
 | A string specifying the domain for the remote connection.
hRasConn
 | A long variable that will store a handle to the remote connection.
hDC
 | A handle to the application form that is making the connection.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASDialOnly

RAS Function Reference

sRASDialOnly

RAS Function Reference

This function initiates a remote connection in synchronous mode.

Declare Function sRASDial Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String, hRasConn As Long, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry to dial.
sUsername
 | A string specifying the username for the remote connection.
sPassword
 | A string specifying the password for the remote connection.
sDomain
 | A string specifying the domain for the remote connection.
hRasConn
 | A long variable that will store a handle to the remote connection.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASGetParams

RAS Function Reference

sRASGetParams

RAS Function Reference

This function retrieves the stored username, password and domain fror the specified connection.

Declare Function sRASGetParams Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal sRASNames As String) As Long

Parameters

sEntryName
 | A string specifying the connection entry name.
sRASNames
 | A string variable used to store the details for the connection. It will store the username, password and domain separated by a bar (|) character. If the phone book was not found the function returns a string stating 'No Phone Book Entry'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASSetParams

RAS Function Reference

sRASSetParams

RAS Function Reference

This function sets the username, password and domain fror the specified connection.

Declare Function sRASSetParams Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal sUsername As String, ByVal sPassword As String, ByVal sDomain As String) As Long

Parameters

sEntryName
 | A string specifying the existing connection entry name.
sUsername
 | A string specifying the username.
sPassword
 | A string specifying the password.
sDomain
 | A string specifying the domain.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASHangUp

RAS Function Reference

sRASHangUp

RAS Function Reference

This function disconnects a connection session.

Declare Function sRASHangUp Lib "SapphireRAS.dll" (ByVal hRasConn As Long) As Long

Parameters

hRasConn
A long variable referencing the handle to the remote connection.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASCurrentConn

RAS Function Reference

sRASCurrentConn

RAS Function Reference

This function retrieves the name and handle to the current connection on the device.

Declare Function sRASCurrentConn Lib "SapphireRAS.dll" (ByRef hRasConn As Long, ByVal sConnName As String) As Long

Parameters

hRasConn
 | A long variable used to store a handle to the current connection.
sConnName
 | A string variable used to store the name of the current connection.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sRASStatus

RAS Function Reference

sRASStatus

RAS Function Reference

This function retrieves the current status of the connection.

Declare Function sRASStatus Lib "SapphireRAS.dll" (ByVal hRasConn As Long) As Long

Parameters

hRasConn
A long variable referencing the handle to the active connection.

Return Values

Returns a number indicating the connection's current state. A value of zero indicates that there is currently no connection initiated. A value of 25 indicates that the connection was lost during the dialing and authentication phase. A value of 1 indicates that the connection was successfully established. Use sRASStatusMsg to get a string version of the connection status.

Status Message Values

Error Number | Message Returned by sRASStatusMsg
0 | Not Connected
1 | Connected
2 | Opening Port
3 | Port Opened
4 | Connecting Device
5 | Device Connected
6 | All Devices Connected
7 | Authenticating
8 | Authenticating
9 | Retrying Authenticating
10 | Requesting Callback Number
11 | Requesting Password Change
12 | Starting Projection Phase
13 | Starting Link-Speed Calculation
14 | Authentication Has Been Acknowledged
15 | Starting Reauthentication
16 | Authentication Successful
17 | Disconnecting For Callback
18 | Resetting Modem
19 | Waiting For Incomming Call
20 | Completed Projection Phase
21 | Terminal State Set
22 | Retry Authentication State Set
23 | Callback State Set
24 | Change Password State Set
25 | Lost Connection
Other | Unknown Message


sRASStatusMsg

RAS Function Reference

sRASStatusMsg

RAS Function Reference

This function retrieves a string value of the specified status number.

Declare Function sRASStatusMsg Lib "SapphireRAS.dll" (ByVal sStatusText As String, ByVal lStatus As Long) As Long

Parameters

sStatusText
 | A string variable used to store the text description of the status. If the status number was not recognised the value will be 'Unknown Message status_number' where status_number represents the number that the function was called with.
lStatus
 | A long value specifiying the status number to lookup.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.

Status Message Values

Error Number | Message Returned by sRASStatusMsg
0 | Not Connected
1 | Connected
2 | Opening Port
3 | Port Opened
4 | Connecting Device
5 | Device Connected
6 | All Devices Connected
7 | Authenticating
8 | Authenticating
9 | Retrying Authenticating
10 | Requesting Callback Number
11 | Requesting Password Change
12 | Starting Projection Phase
13 | Starting Link-Speed Calculation
14 | Authentication Has Been Acknowledged
15 | Starting Reauthentication
16 | Authentication Successful
17 | Disconnecting For Callback
18 | Resetting Modem
19 | Waiting For Incomming Call
20 | Completed Projection Phase
21 | Terminal State Set
22 | Retry Authentication State Set
23 | Callback State Set
24 | Change Password State Set
25 | Lost Connection
Other | Unknown Message


sRASErrMsg

RAS Function Reference

sRASErrMsg

RAS Function Reference

This function retrieves a string value of the specified error number.

Declare Function sRASErrMsg Lib "SapphireRAS.dll" (ByVal sErrorText As String, ByVal lError As Long) As Long

Parameters

sErrorText
 | A string variable used to store the text description of the error. If the error number was not recognised the value will be 'Undefined Error'.
lStatus
 | A long value specifiying the error number to lookup.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.

Error Message Values

Error Number | Message Returned by sRASErrMsg
123 | Phone Book Entry Invalid Name
183 | Phone Book Entry Already Exists
601 | Invalid Port Handle
602 | Port Already Open
603 | Buffer Too Small
604 | Wrong Info Specified
605 | Cannot Set Port Info
606 | Port Not Connected
607 | Event Invalid
608 | Device Does Not Exist
609 | Device Type Does Not Exist
610 | Buffer Invalid
611 | Route Not Available
612 | Route Not Allocated
613 | Invalid Compression Specified
614 | Out Of Buffers
615 | Port Not Found
616 | Async Request Pending
617 | Already Disconnecting
618 | Port Not Open
619 | Port Disconnected
620 | No End Points
621 | Can Not Open Phone Book
622 | Can Not Load Phone Book
623 | Can Not Find Phone Book Entry
624 | Can Not Write Phone Book
625 | Corrupt Phone Book
626 | Cannot Load String
627 | Key Not Found
628 | Disconnection
629 | Remote Disconnection
630 | Hardware Failure
631 | User Disconnection
632 | Invalid Size
633 | Port Not Available
634 | Can Not Project Client
635 | Unknown
636 | Wrong Device Attached
637 | Bad String
638 | Request Timeout
639 | Can Not Get Lana
640 | Net Bios Error
641 | Server Out Of Resources
642 | Name Exists On Net
643 | Server General Net Failure
644 | Alias Not Added
645 | Auth Internal
646 | Restricted Logon Hours
647 | Acct Disabled
648 | Password Expired
649 | No Dialing Permission
650 | Server Not Responding
651 | From Device
652 | Unrecognised Response
653 | Macro Not Found
654 | Macro Not Defined
655 | Message Macro Not Found
656 | Default Off Macro Not Found
657 | File Could Not Be Opened
658 | Device Name Too Long
659 | Device Name Not Found
660 | No Responses
661 | No Command Found
662 | Wrong Key Specified
663 | Unknown Device Type
664 | Allocating Memory
665 | Port Not Configured
666 | Device Not Ready
667 | Reading Ini File
668 | No Connection
669 | Bad Usage In Ini File
670 | Reading Section Name
671 | Reading Device Type
672 | Reading Device Name
673 | Reading Usage
674 | Reading Max Connection BPS
675 | Reading Max Carrier BPS
676 | Line Busy
677 | Voice Answer
678 | No Answer
679 | No Carrier
680 | No Dial Tone
681 | In Command
682 | Writing Section Name
683 | Writing Device Type
684 | Writing Device Name
685 | Writing Max Connection BPS
686 | Writing Max Carrier BPS
687 | Writing Usage
688 | Writing Default Off
689 | Reading Default Off
690 | Empty Ini File
691 | Authentication Failure
692 | Port Or Device
693 | Not Binary Macro
694 | DCB Not Found
695 | State Machines Not Started
696 | State Machines Already Started
697 | Partial Response Looping
698 | Unknown Response Key
699 | Receive Buffer Full
700 | Command Too Long
701 | Unsupported BPS
702 | Unexpected Response
703 | Interactive Mode
704 | Bad Callback Number
705 | Invalid Auth State
706 | Writing Init BPS
707 | X25 Diagnostic
708 | Account Expired
709 | Changing Password
710 | Overrun
711 | RAS Manager Can Not Initialise
712 | Biplex Port Not Available
713 | No Active ISDN Lines
714 | No ISDN Channels Available
715 | Too Many Line Errors
716 | IP Configuration
717 | No IP Addresses
718 | PPP Timeout
719 | PPP Remote Terminated
720 | PPP No Protocols Configured
721 | PPP No Response
722 | PPP Invalid Packet
723 | Phone Number Too Long
724 | IPXCP No Dial Out Configured
725 | IPXCP No Dialing Configured
726 | IPXCP Dial Out Already Active
727 | Accessing TCPCFGDLL
728 | No IP RAS Adapter
729 | SLIP Requires IP
730 | Projection Not Complete
731 | Protocol Not Configured
732 | PPP Not Configured
733 | PPP CP Rejected
734 | PPP LCP Terminated
735 | PPP Required Address Rejected
736 | PPP NCP Terminated
737 | PPP Loopback Detected
738 | PPP No Address Assigned
739 | Can Not Use Logon Credentials
740 | TAPI Configuration
741 | No Local Encryption
742 | No Remote Encryption
743 | Remote Requires Encryption
744 | IPXCP Net Number Conflict
745 | Invalid SMM
746 | SMM Uninitialized
747 | No MAC For Port
748 | SMM Timeout
749 | Bad Phone Number
750 | Wrong Module
751 | PPP MAC
752 | PPP LCP
753 | PPP Auth
754 | PPP NCP
755 | Power Off
756 | Power Off CD
Other | Undefined Error


sPBGet

RAS Function Reference

sPBGet

RAS Function Reference

This function retrieves the specified phone book properties.

Declare Function sPBGet Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal sPBData As String, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
sPBData
 | A string variable used to store the phone book properties into separated by a bar (|) character. If the phone book was not found the value will be 'No Such Phone Book Entry'. If the operation failed the function returns a string stating 'Problem Retrieving Phone Book Entry'.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBSet

RAS Function Reference

sPBSet

RAS Function Reference

This function sets the phone book properties.

Declare Function sPBSet Lib "SapphireRAS.dll" (ByVal sEntryName As String, _
ByVal sNumbers As String, ByVal sExtraInfo As String, ByVal sSettings As String, _
ByVal lPBBefore As Long, ByVal lPBAfter As Long, _
ByVal lPBManually As Long, ByVal lPBWait As Long, _
ByVal lUseCountryAndAreaCodes As Long, ByVal lDialAsLocalCall As Long, _
ByVal lSpecificIpAddr As Long, ByVal sIPAddress As String, _
ByVal lSpecificNameServers As Long, ByVal sIPAddresses As String, _
ByVal lIpHeaderCompression As Long, ByVal lSwCompression As Long, _
ByVal lSlip As Long, ByVal lGPRS As Long, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
sNumbers
 | A string comprising of the country code, area code, local phone number, device name and device type separated by the bar (|) character. If setting a GPRS connection, set the telephone number to ~GPRS!
sExtraInfo
 | A string comprising of the flow control, credit card tone timeout, extra dialing command string and connection manager name (PPC2002 only) separated by the tilder (~) character.
sSettings
 | A string comprising of the dial-up timeout, baud rate, data bits, parity and stop bits separated by the bar (|) character.
lPBBefore
 | A long specifying the use terminal before connecting parameter. 1 = yes, 0 = no.
lPBAfter
 | A long variable specifying the use terminal after connection parameter. 1 = yes, 0 = no.
lPBManually
 | A long specifying the enter dialing commands manually parameter. 1 = yes, 0 = no.
lPBWait
 | A long specifying the wait for dial tone before dialing. 1 = yes, 0 = no.
lUseCountryAndAreaCodes
 | A long specifying the user country and area codes parameter. 1 = yes, 0 = no.
lDialAsLocalCall
 | A long specifying the dial as local call parameter. 1 = yes, 0 = no.
lSpecificIpAddr
 | A long specifying the use specific IP address parameter. 1 = yes, 0 = no.
sIPAddress
 | A string specifying the IP address to use with each element of the address separated by the tilder (~) character.
lSpecificNameServers
 | A long specifying the use specific server address parameter. 1 = yes, 0 = no.
sIPAddresses
 | A string specifying the IP address of the DNS server, alternative DNS server, WINS server and alternative WINS server. Each element address and each element of each address is separated by the tilder (~) character.
lIpHeaderCompression
 | A long specifying whether to use header compression. 1 = yes, 0 = no.
lSwCompression
 | A long specifying whether to use software compression. 1 = yes, 0 = no.
lSlip
 | A long specifying whether to use slip. 1 = yes, 0 = no.
lGPRS
 | A long specifying whether the connection is a GPRS connection. 1 = yes, 0 = no.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBValidate

RAS Function Reference

sPBValidate

RAS Function Reference

This function checks if the specified connection entry name is in a valid format.

Declare Function sPBValidate Lib "SapphireRAS.dll" (ByVal sEntryName As String) As Long

Parameters

sEntryName
A string specifying the name of the phone book entry.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBDelete

RAS Function Reference

sPBDelete

RAS Function Reference

This function deletes a connection entry from the connection manager.

Declare Function sPBDelete Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBRename

RAS Function Reference

sPBRename

RAS Function Reference

This function renames a connection entry.

Declare Function sPBRename Lib "SapphireRAS.dll" (ByVal sOldEntryName As String, ByVal sNewEntryName As String, ByVal lLicence As Long) As Long

Parameters

sOldEntryName
 | A string specifying the name of the phone book entry to rename.
sNewEntryName
 | A string specifying the name to rename the connection entry to.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBNames

RAS Function Reference

sPBNames

RAS Function Reference

This function returns a list of connection entries that exist in the phone book.

Declare Function sPBNames Lib "SapphireRAS.dll" (ByRef lEntries As Long, ByVal sRASNames As String) As Long

Parameters

lEntries
 | A long variable used to store the number of phone book entries returned
sRASNames
 | A string variable used to store the list of entry names separated by the bar (|) character. If there are no connection entries the value will be 'No Phone Book Entries'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBDevices

RAS Function Reference

sPBDevices

RAS Function Reference

This function returns a list of devices.

Declare Function sPBDevices Lib "SapphireRAS.dll" (ByRef lEntries As Long, ByVal sRASNames As String) As Long

Parameters

lEntries
 | A long variable used to store the number of devices entries returned
sDevices
 | A string variable used to store the list of devices separated by the bar (|) character. If there are no devices the value will be 'No Device Names'.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBGetWorkInternet

RAS Function Reference

sPBGetWorkInternet

RAS Function Reference

This function identifies whether the device is currently set for work or Internet dial-up.

Declare Function sPBGetWorkInternet Lib "SapphireRAS.dll" () As Long

Parameters

None

Return Values

Returns 1 if it is configured for work, or 2 if it is configured for the Internet.


sPBSetWorkInternet

RAS Function Reference

sPBSetWorkInternet

RAS Function Reference

This function sets the devices work or Internet dial-up settings.

Declare Function sPBSetWorkInternet Lib "SapphireRAS.dll" (ByVal lNumber As Long) As Long

Parameters

lNumber
A long specifying the work or Internet option. 1 = Work, 2 = Internet.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sPBSetDefault

RAS Function Reference

sPBSetDefault

RAS Function Reference

This function ets the specified phone book entry as default

Declare Function sPBSetDefault Lib "SapphireRAS.dll" (ByVal sEntryName As String, ByVal lLicence As Long) As Long

Parameters

sEntryName
 | A string specifying the name of the phone book entry to set as default.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetCurrent

RAS Function Reference

sLOCGetCurrent

RAS Function Reference

This function returns a number referencing the current dialing location.

Declare Function sLOCGetCurrent Lib "SapphireRAS.dll" () As Long

Parameters

None

Return Values

Returns a number referencing the current dialing location.


sLOCSetCurrent

RAS Function Reference

sLOCSetCurrent

RAS Function Reference

This function sets the current dialing location.

Declare Function sLOCSetCurrent Lib "SapphireRAS.dll" (ByVal lNumber As Long) As Long

Parameters

lNumber
A long referencing the dialing location to set as the current.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetNumber

RAS Function Reference

sLOCGetNumber

RAS Function Reference

This function gets the number of available locations.

Declare Function sLOCGetNumber Lib "SapphireRAS.dll" () As Long

Parameters

None

Return Values

Returns the number of available locations.


sLOCSetNumber

RAS Function Reference

sLOCSetNumber

RAS Function Reference

This function sets the current location dialing number.

Declare Function sLOCSetNumber Lib "SapphireRAS.dll" (ByVal lNumber As Long) As Long

Parameters

lNumber
A long number representing the location dialing number.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCGetLocation

RAS Function Reference

sLOCGetLocation

RAS Function Reference

This function retrieves a specified location details.

Declare Function sLOCGetLocation Lib "SapphireRAS.dll" (ByVal lNumber As Long, ByVal sLocations As String) As Long

Parameters

lNumber
 | A long number representing the location to retrieve the details from.
sLocations
 | A string variable used to store the list of location properties separated by the bar (|) character.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCSetLocation

RAS Function Reference

sLOCSetLocation

RAS Function Reference

This function sets the location properties.

Declare Function sLOCSetLocation Lib "SapphireRAS.dll" (ByVal lNumber As Long, ByVal sSettings As String) As Long

Parameters

lNumber
 | A long number representing the location to set the details for.
sSettings
 | A string comprised of the location name, local calls, long distance, international, area code, call waiting, country code and dialing tone (0 = tone, 1 = pulse) separated by the bar (|) character.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


sLOCDeleteLocation

RAS Function Reference

sLOCDeleteLocation

RAS Function Reference

This function deletes a dialing location.

Declare Function sLOCDeleteLocation Lib "SapphireRAS.dll" (ByVal lNumber As Long) As Long

Parameters

lNumber
A long number representing the location to delete.

Return Values

Returns a number indicating success or failure where 0 is successful. Use sRASErrMsg to get a string version of the error message.


Sapphire FTP Utility

Sapphire FTP Utility Contents

The Sapphire FTP Utility is designed for connecting to a remote FTP server, sending and receiving files and full file management. This document is for version 5.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire FTP Utility is designed for eVB and VB.NET developers allowing an application to use File Transfer Protocol (FTP) functionality. The utility is capable of doing the following:

  • Open a FTP session
  • Close a FTP session
  • Upload and download files
  • Remote directory navigation
  • Retrieve the current remote directory path
  • Search for files and directories with attributes
  • Remove files and directories
  • Rename files and directories
  • Make directories
  • Upload and download directories and contents
  • Check if a remote file exists

Version History

v5.0 | Added support to stream an upload or download in 1KB chunks allowing feedback to the eVB/VB.NET application. Improved error reporting on file uploads and downloads
v4.0 | VB.NET Compatible
v3.0 | Added passive mode connections. Added custom port number specification.
v2.0 | Added the ability to search for files using a filter. Added a sFTPReconnect to allow enforce correct lookups are made from the remote FTP server.
v1.01 | First release of the Sapphire FTP Utility. Functions included: sFTPOpen, sFTPGet, sFTPPut, sFTPClose, sFTPPull, sFTPPush, sFTPFindFirstFile, sFTPFindNextFile, sFTPChangeDirectory, sFTPCurrentDirectory, sFTPRemoveFile, sFTPRenameFile, sFTPRemoveDirectory, sFTPMakeDirectory, sFTPErrorText, sFTPFileExists, sFTPUploadDirectory, sFTPDownloadDirectory


Supported Hardware

The current supported hardware for the Sapphire FTP Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HDT600-SH4
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86
  • Windows32

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire FTP Utility comes with a demo project that shows how to connect to a remote FTP server and send and receive files. The demo also shows how to use FTP to synchronise a local directory with a remote directory in a similar manner to ActiveSync. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

Main Application Screen
FTP Menu Screen
FTP Explorer
FTP Synchronisation
FTP Settings


FTP Menu Screen

This menu gives the options for the FTP specific functionality.

FTP Explorer
This is a local and remote explorer where files can be transferred to and from the remote FTP server.

FTP Sync
This performs a FTP Synchronisation routine that tests for any local or remote changes and then uploads or downloads the necessary files.

FTP Settings
This allows the FTP connections to be configured.

The Back button takes returns to the main application screen.


FTP Explorer

The FTP Explorer screen allows advanced file management between the local drive and the remote FTP server. Most of the functionality has been developed using eVB/VB.NET and uses the Sapphire FTP Utility to perform the FTP specific functions.

Connect / Disconnect
Use the connect button to establish a connection to the remote FTP server (defined under FTP Settings). The status on the top right will tell you if the application is connected or disconnected to the remote server. Use the disconnect button to close the FTP session.

Navigation
Whether you are navigating the local directory or remote directory you can use the scroll bars to show all files and directories. Directories are identified by the items that are surrounded by square brackets. The directory title will show as bold to indicate whether the local or remote list is active.

Filters
Pressing the 'Flt' button will show a prompt where you can enter a filter on the files shows. For example, to show all remote or local files you can enter '*.*' or '*.zip' to show all zip files.

Upload
To upload a file or directory, select the item you wish to upload on the local directory and select upload. The application will check to see if the remote file already exists on the remote server and will ask if you wish to overwrite the file.

Download
This works similar to the upload button except you must select a file or directory on the remote server that you wish to download.

Make Directory
To create a directory, either on the local or remote drive, select the list to create it in and click 'MK Dir'. A prompt will appear for you to enter the name of the directory to create where you can either submit the request or cancel.

Delete
The delete function can be used to delete a file or directory (including contents) either on the local or remote drive. When you select the item you wish to delete and click 'Delete' you will receive a confirmation prompt where you can select 'Yes' or 'No' on whether to continue deleting.

Rename file or directory
It is possible to rename a file or directory simply by selecting the item you wish to rename on the local or remote drive. When selected, tap the name of the item and it will bring up an edit field. Files will allow you to edit the name directly on the list and directories will show a popup field. To cancel the edit, either press 'Escape' or 'Cancel' button.

Open Directory
To open a directory on the local or remote drive, select the directory you wish to open and click 'Open Dir'. Trying to use 'Open Dir' on files will simply be ignored. To move to a parent directory, select '[..]' and click 'Open Dir'.

Refresh
Should the contents of the local or remote drive be changed, you may wish to refresh the list to see such changes. Select the list you wish to update and click the 'Refresh' button.

Zoom
The 'Zoom' button allows you to show the local, remote or both lists on the screen at any one time.

Back
The 'Back' button returns to the main application screen. If you are still connected to a remote FTP server then you will be prompted to disconnect your connection.


FTP Synchronisation

The the FTP Sync button is pressed on the FTP menu, the demo connects to the remote FTP server and performs the synchronisation routine. It works by storing the contents of the remote server and the contents of the local directory to two local text files at the end of a synchronisation. When the actual files have changed since it last synchronised the demo can build up an action list on whether a file was removed, added or modified.

If a file on both the server and the local drive were modified, the demo can be configured to either have the device take priority, the FTP server take priority or the newest file take priority.

Pressing the Close button returns to the FTP menu.


FTP Settings

Included in the demo is a test server which is available for use by anyone who simply wishes to test the utility.

There are various settings that you can specify for the demo application.

Local Path is the local directory to use when running the FTP Synchronisation routine.
Remote Path is the remote FTP directory to use when running the FTP Synchronisation routine.
FTP Host is the domain name or IP address of the remote FTP server.
Username is the account username for the FTP account.
Password is the account password for the FTP account.
Use passive mode option specifies whether to make a passive or non-passive connection.

If you require to connect as an anonymous user then simply enter Anonymous as the username and your email address as the password.

Apply confirms the changes and Back returns to the FTP menu.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sFTPOpen | Opens a connection to a remote FTP server
sFTPClose | Closes a FTP connection
sFTPGet | Download a remote file
sFTPPut | Upload a local file
sFTPPull | Download a remote file (PPC2002 compatible)
sFTPPullStart | Starts a download stream
sFTPPullMore | Reads the next chunk of the download
sFTPPullEnd | Ends the download
sFTPPush | Upload a local file (PPC2002 compatible)
sFTPPushStart | Starts an upload stream
sFTPPushMore | Sends the next chunck for the upload
sFTPPushEnd | Ends the upload
sFTPDownloadDirectory | Downloads a directory with contents
sFTPUploadDirectory | Uploads a directory with contents
sFTPFindFirstFile | Find the first file in the current FTP directory
sFTPFindNextFile | Find the next file
sFTPCurrentDirectory | Retrieve the current FTP directory
sFTPChangeDirectory | Change the FTP directory
sFTPRemoveFile | Remote a remote file
sFTPRemoveDirectory | Remote a remote directory including contents
sFTPRenameFile | Rename a remote file or directory
sFTPMakeDirectory | Make a remote directory
sFTPFileExists | Checks if a remote file exists
sFTPErrorText | Returns a text version of the FTP error
sFTPReconnect | Performs a reconnect to the remote FTP server

Appendix

Error Codes | List of FTP error codes
Parameter Codes | List of parameter options


sFTPOpen

FTP Function Reference

sFTPOpen

FTP Function Reference

This function establishes a connection with a remote FTP server running over an IP network.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPOpen(ByVal sServer As String, ByVal lPort As Integer, ByVal sUser As String, ByVal sPwd As String, ByVal lPassive As Integer, ByVal lTimeOut As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sServer
 | A string specifying the remote server to connect to. This can either be a domain or an IP address.
lPort
 | A long specifying the port number of the running FTP server. This value is commonly 21 for standard FTP connections.
sUser
 | A string specifying the username for the FTP account.
sPwd
 | A string specifying the password for the FTP account.
lPassive
 | An integer flag specifying whether to use passive mode or not. Setting this parameter to 1 will use passive mode and setting to 0 will use active mode.
lTimeOut
 | An integer value specifying the connection timeout in milliseconds.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

If you are calling sFTPOpen on PPC2002, please ensure that you have the latest patch called EUU2 (downloadable from your manufacturers web site) installed as early releases of the operating system would not allow FTP connections that were not anonymous.


sFTPClose

FTP Function Reference

sFTPClose

FTP Function Reference

This function disconnects from the remote FTP server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPClose(ByVal lLicense As Integer) As Integer
End Function

Parameters

lLicence
An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPGet

FTP Function Reference

sFTPGet

FTP Function Reference

This function downloads a file from the remote FTP server to the local drive.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPGet(ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal bOverWriteFile As Byte, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
bOverWriteFile
 | A byte indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | An integer specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The sFTPGet function does not work on PPC2002 and has been included for backwards compatibility. Use sFTPPull if your application may be running on PPC2002.


sFTPPut

FTP Function Reference

sFTPPut

FTP Function Reference

This function uploads a file from the local drive to the remote FTP server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPut(ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | An integer specifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The sFTPPut function does not work on PPC2002 and has been included for backwards compatibility. Use sFTPPush if your application may be running on PPC2002.


sFTPPull

FTP Function Reference

sFTPPull

FTP Function Reference

This function downloads a file from the remote FTP server to the local drive.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPull(ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal bOverWriteFile As Byte, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
bOverWriteFile
 | A byte indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | An integer specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullStart

FTP Function Reference

sFTPPullStart

FTP Function Reference

This function starts a download stream with the remote server. You must use sFTPPullMore and sFTPPullEnd to complete the transfer.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPullStart(ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal bOverWriteFile As Byte, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
lOverWriteFile
 | An integer indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | An integer specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullMore

FTP Function Reference

sFTPPullMore

FTP Function Reference

This function download the next chunk in the stream. You must use sFTPPullStart to start the download stream and sFTPPullEnd to close the stream upon completion.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPullMore() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullEnd

FTP Function Reference

sFTPPullEnd

FTP Function Reference

This function closes a download stream.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPullEnd() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPush

FTP Function Reference

sFTPPush

FTP Function Reference

This function uploads a file from the local drive to the remote FTP server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPush(ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | An integer specifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushStart

FTP Function Reference

sFTPPushStart

FTP Function Reference

This function starts an upload stream to the remote server. You must use sFTPPushMore and sFTPPushEnd to complete the transfer.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPushStart(ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | An integerspecifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushMore

FTP Function Reference

sFTPPushMore

FTP Function Reference

This function uploads the next chunk of data to the remote FTP server. You must start the upload with sFTPPushStart and finish with sFTPPushEnd.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPushMore() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushEnd

FTP Function Reference

sFTPPushEnd

FTP Function Reference

This function closes an upload stream.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPPushEnd() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPDownloadDirectory

FTP Function Reference

sFTPDownloadDirectory

FTP Function Reference

This function downloads a remote directory and any containing files and sub directories.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPDownloadDirectory(ByVal sRemoteDirectory As String, ByVal sLocalPath As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sRemoteDirectory
 | A string specifying the name of the remote directory to download.
sLocalPath
 | A string specifying the path on the local device where to download the remote directory to.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The same directory must not already exist on the local drive otherwise an error will occur.

The local path must not include a trailing slash.

The function will only download up to 10 sub directories per directory node.


sFTPUploadDirectory

FTP Function Reference

sFTPUploadDirectory

FTP Function Reference

This function uploads a local directory and any containing files and sub directories. The directory gets created on the current remote directory.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPUploadDirectory(ByVal sLocalDirectory As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sLocalDirectory
 | A string specifying the path of the local directory to upload.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The same directory must not already exist on the remote server otherwise an error will occur.

The local path must not include a trailing slash.

The function will only upload up to 10 sub directories per directory node.


sFTPFindFirstFile

FTP Function Reference

sFTPFindFirstFile

FTP Function Reference

This function searches for the first file or directory in the current remote directory.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPFindFirstFile(ByVal sFileString As String, ByVal sFilter As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sFileString
 | A string variable that is used to return the details of the first found item.
sFilter
 | A string specifying a filter to perform a more specific search.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether a file was found. If there were no files found the value will be 0.


sFTPFindNextFile

FTP Function Reference

sFTPFindNextFile

FTP Function Reference

This function searches for the next file after a call to the sFTPFindFirstFile.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPFindNextFile(ByVal sFileString As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sFileString
 | A string variable that is used to return the details of the next file found.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether a file was found. If there were no files found the value will be 0.


sFTPCurrentDirectory

FTP Function Reference

sFTPCurrentDirectory

FTP Function Reference

This function retrieves the path of the current remote FTP directory.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPCurrentDirectory(ByVal sCurrentDirectory As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sCurrentDirectory
 | A string variable that is used to store the name of the current remote FTP directory.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPChangeDirectory

FTP Function Reference

sFTPChangeDirectory

FTP Function Reference

This function changes to the specified directory on the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPChangeDirectory(ByVal sPath As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sPath
 | A string specifying the absolute or relative path to the directory to change to.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPRemoveFile

FTP Function Reference

sFTPRemoveFile

FTP Function Reference

This function removes a file from the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPRemoveFile(ByVal sRemoteFile As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sRemoteFile
 | A string specifying the name of the remote file to remove.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPRemoveDirectory

FTP Function Reference

sFTPRemoveDirectory

FTP Function Reference

This function removes a directory on the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPRemoveDirectory(ByVal sDirectory As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sDirectory
 | A string specifying the remote directory to remove.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The function will only remove if there are 10 or less sub directories per child directory node.


sFTPRenameFile

FTP Function Reference

sFTPRenameFile

FTP Function Reference

This function renames a remote file or directory in the current path on the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPRenameFile(ByVal sOldFile As String, ByVal sNewFile As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sOldFile
 | A string specifying the remote file or directory to rename.
sNewFile
 | A string specifying the remote file or directory to rename to.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPMakeDirectory

FTP Function Reference

sFTPMakeDirectory

FTP Function Reference

This function creates a directory in the current path on the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPMakeDirectory(ByVal sDirectory As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sDirectory
 | A string specifying the remote directory to create.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPFileExists

FTP Function Reference

sFTPFileExists

FTP Function Reference

This function checks to see if a file or directory exists on the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPFileExists(ByVal sFile As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sFile
 | A string specifying the name of the file or directory to see if it exists.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether the file exists or not where 1 means the file exists and 0 means it does not.

Remarks

You cannot call sFTPFileExists between calls to sFTPFindFirstFile and sFTPFindNextFile. Calling sFTPFileExists close all previous file searches.


sFTPErrorText

FTP Function Reference

sFTPErrorText

FTP Function Reference

This routine retrieves a text version of an error number returned from a previous function.

<DllImport("SapphireFTP.dll")> _
Public Sub sFTPErrorText(ByVal sErrorText As String, ByVal lError As Integer)
End Sub

Parameters

sErrorText
 | A string variable that will be used to store the text description of the error. If the error number is not recognised then it will return 'unknown error' and the system error number.
lError
 | An integer specifying number of the error to lookup.

Return Values

None


sFTPReconnect

FTP Function Reference

sFTPReconnect

FTP Function Reference

This function reestablishes a connection to the remote server to ensure that the correct information is retrieved from the remote server.

<DllImport("SapphireFTP.dll")> _
Public Function sFTPReconnect(ByVal lPassive As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

lPassive
 | An integer flag specifying whether to use passive mode or not. Setting this parameter to 1 will use passive mode and setting to 0 will use active mode.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether the reconnect procedure was successful or not. 1 = Successful, 0 = Failed.


Error Codes

FTP Error Codes

Error Codes

FTP Function Reference

The following is a list of error codes that are defined in your VB.NET project.

Public Const FTP_NO_ERROR = 0
Public Const FTP_TOO_MANY_INTERNET_HANDLES = 1
Public Const FTP_TIMEOUT = 2
Public Const FTP_INTERNAL_ERROR = 3
Public Const FTP_INVALID_URL = 4
Public Const FTP_NAME_NOT_RESOLVED = 5
Public Const FTP_PROTOCOL_NOT_FOUND = 6
Public Const FTP_SHUTDOWN = 7
Public Const FTP_INCORRECT_USER_NAME = 8
Public Const FTP_INCORRECT_PASSWORD = 9
Public Const FTP_LOGIN_FAILED = 10
Public Const FTP_REQUEST_PENDING = 11
Public Const FTP_CANNOT_CONNECT = 12
Public Const FTP_CONNECTION_ABORTED = 13
Public Const FTP_CONNECTION_RESET = 14
Public Const FTP_FORCE_RETRY = 15
Public Const FTP_INVALID_PROXY_REQUEST = 16
Public Const FTP_TRANSFER_IN_PROGRESS = 17
Public Const FTP_DROPPED = 18
Public Const FTP_NO_PASSIVE_MODE = 19
Public Const FTP_LOCAL_FILE_EXISTS = 20
Public Const FTP_UNKNOWN = 21


Parameter Codes

FTP Parameter Codes

Parameter Codes

FTP Function Reference

The following is a list of parameter codes that are defined in your VB.NET project.

' Overwrite modes
Public Const FTP_OVERWRITE = 1
Public Const FTP_DONT_OVERWRITE = 0

' Transfer modes
Public Const FTP_TRANSFER_UNKNOWN = 0
Public Const FTP_TRANSFER_ASCII = 1
Public Const FTP_TRANSFER_BINARY = 2

Public Const DEFAULT_FTP_PORT = 21


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sFTPOpen | Opens a connection to a remote FTP server
sFTPClose | Closes a FTP connection
sFTPGet | Download a remote file
sFTPPut | Upload a local file
sFTPPull | Download a remote file (PPC2002 compatible)
sFTPPullStart | Starts a download stream
sFTPPullMore | Reads the next chunk of the download
sFTPPullEnd | Ends the download
sFTPPush | Upload a local file (PPC2002 compatible)
sFTPPushStart | Starts an upload stream
sFTPPushMore | Sends the next chunck for the upload
sFTPPushEnd | Ends the upload
sFTPDownloadDirectory | Downloads a directory with contents
sFTPUploadDirectory | Uploads a directory with contents
sFTPFindFirstFile | Find the first file in the current FTP directory
sFTPFindNextFile | Find the next file
sFTPCurrentDirectory | Retrieve the current FTP directory
sFTPChangeDirectory | Change the FTP directory
sFTPRemoveFile | Remote a remote file
sFTPRemoveDirectory | Remote a remote directory including contents
sFTPRenameFile | Rename a remote file or directory
sFTPMakeDirectory | Make a remote directory
sFTPFileExists | Checks if a remote file exists
sFTPErrorText | Returns a text version of the FTP error
sFTPReconnect | Performs a reconnect to the remote FTP server

Appendix

Error Codes | List of FTP error codes
Parameter Codes | List of parameter options


sFTPOpen

FTP Function Reference

sFTPOpen

FTP Function Reference

This function establishes a connection with a remote FTP server running over an IP network.

Declare Function sFTPOpen Lib "SapphireFTP.dll" (ByVal sServer As String, ByVal lPort As Long, ByVal sUser As String, ByVal sPwd As String, ByVal lPassive As Long, ByVal lTimeOut As Long, ByVal lLicence As Long) As Long

Parameters

sServer
 | A string specifying the remote server to connect to. This can either be a domain or an IP address.
lPort
 | A long specifying the port number of the running FTP server. This value is commonly 21 for standard FTP connections.
sUser
 | A string specifying the username for the FTP account.
sPwd
 | A string specifying the password for the FTP account.
lPassive
 | A long flag specifying whether to use passive mode or not. Setting this parameter to 1 will use passive mode and setting to 0 will use active mode.
lTimeOut
 | A long value specifying the connection timeout in milliseconds.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

If you are calling sFTPOpen on PPC2002, please ensure that you have the latest patch called EUU2 (downloadable from your manufacturers web site) installed as early releases of the operating system would not allow FTP connections that were not anonymous.


sFTPClose

FTP Function Reference

sFTPClose

FTP Function Reference

This function disconnects from the remote FTP server.

Declare Function sFTPClose Lib "SapphireFTP.dll" (ByVal lLicense As Long) As Long

Parameters

lLicence
A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPGet

FTP Function Reference

sFTPGet

FTP Function Reference

This function downloads a file from the remote FTP server to the local drive.

Declare Function sFTPGet Lib "SapphireFTP.dll" (ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal lOverWriteFile As Long, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
lOverWriteFile
 | A long indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | A long specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The sFTPGet function does not work on PPC2002 and has been included for backwards compatibility. Use sFTPPull if your application may be running on PPC2002.


sFTPPut

FTP Function Reference

sFTPPut

FTP Function Reference

This function uploads a file from the local drive to the remote FTP server.

Declare Function sFTPPut Lib "SapphireFTP.dll" (ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | A long specifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The sFTPPut function does not work on PPC2002 and has been included for backwards compatibility. Use sFTPPush if your application may be running on PPC2002.


sFTPPull

FTP Function Reference

sFTPPull

FTP Function Reference

This function downloads a file from the remote FTP server to the local drive.

Declare Function sFTPPull Lib "SapphireFTP.dll" (ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal lOverWriteFile As Long, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
lOverWriteFile
 | A long indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | A long specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullStart

FTP Function Reference

sFTPPullStart

FTP Function Reference

This function starts a download stream with the remote server. You must use sFTPPullMore and sFTPPullEnd to complete the transfer.

Declare Function sFTPPullStart Lib "SapphireFTP.dll" (ByVal sRemoteFile As String, ByVal sLocalFile As String, ByVal lOverWriteFile As Long, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sRemoteFile
 | A string specifying the name of the remote file to retrieve.
sLocalFile
 | A string specifying the name of the new local file the remote data will be copied to.
lOverWriteFile
 | A long indicating whether to overwrite an existing local file. Use FTP_OVERWRITE and FTP_DONT_OVERWRITE for this parameter.
lTransferType
 | A long specifying how the function will handle the download. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullMore

FTP Function Reference

sFTPPullMore

FTP Function Reference

This function download the next chunk in the stream. You must use sFTPPullStart to start the download stream and sFTPPullEnd to close the stream upon completion.

Declare Function sFTPPullMore Lib "SapphireFTP.dll" () As Long

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPullEnd

FTP Function Reference

sFTPPullEnd

FTP Function Reference

This function closes a download stream.

Declare Function sFTPPullEnd Lib "SapphireFTP.dll" () As Long

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPush

FTP Function Reference

sFTPPush

FTP Function Reference

This function uploads a file from the local drive to the remote FTP server.

Declare Function sFTPPush Lib "SapphireFTP.dll" (ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | A long specifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushStart

FTP Function Reference

sFTPPushStart

FTP Function Reference

This function starts an upload stream to the remote server. You must use sFTPPushMore and sFTPPushEnd to complete the transfer.

Declare Function sFTPPushStart Lib "SapphireFTP.dll" (ByVal sLocalFile As String, ByVal sRemoteFile As String, ByVal lTransferType As Long, ByVal lLicence As Long) As Long

Parameters

sLocalFile
 | A string specifying the name of the local file to upload.
sRemoteFile
 | A string specifying the name of the new remote file the local data will be copied to.
lTransferType
 | A long specifying how the function will handle the upload. Use one of the following: FTP_TRANSFER_UNKNOWN FTP_TRANSFER_ASCII FTP_TRANSFER_BINARY
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushMore

FTP Function Reference

sFTPPushMore

FTP Function Reference

This function uploads the next chunk of data to the remote FTP server. You must start the upload with sFTPPushStart and finish with sFTPPushEnd.

Declare Function sFTPPushMore Lib "SapphireFTP.dll" () As Long

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPPushEnd

FTP Function Reference

sFTPPushEnd

FTP Function Reference

This function closes an upload stream.

Declare Function sFTPPushEnd Lib "SapphireFTP.dll" () As Long

Parameters

None

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPDownloadDirectory

FTP Function Reference

sFTPDownloadDirectory

FTP Function Reference

This function downloads a remote directory and any containing files and sub directories.

Declare Function sFTPDownloadDirectory Lib "SapphireFTP.dll" (ByVal sRemoteDirectory As String, ByVal sLocalPath As String, ByVal lLicence As Long) As Long

Parameters

sRemoteDirectory
 | A string specifying the name of the remote directory to download.
sLocalPath
 | A string specifying the path on the local device where to download the remote directory to.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The same directory must not already exist on the local drive otherwise an error will occur.

The local path must not include a trailing slash.

The function will only download up to 10 sub directories per directory node.


sFTPUploadDirectory

FTP Function Reference

sFTPUploadDirectory

FTP Function Reference

This function uploads a local directory and any containing files and sub directories. The directory gets created on the current remote directory.

Declare Function sFTPUploadDirectory Lib "SapphireFTP.dll" (ByVal sLocalDirectory As String, ByVal lLicence As Long) As Long

Parameters

sLocalDirectory
 | A string specifying the path of the local directory to upload.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The same directory must not already exist on the remote server otherwise an error will occur.

The local path must not include a trailing slash.

The function will only upload up to 10 sub directories per directory node.


sFTPFindFirstFile

FTP Function Reference

sFTPFindFirstFile

FTP Function Reference

This function searches for the first file or directory in the current remote directory.

Declare Function sFTPFindFirstFile Lib "SapphireFTP.dll" (ByVal sFileString As String, ByVal sFilter As String, ByVal lLicence As Long) As Long

Parameters

sFileString
 | A string variable that is used to return the details of the first found item.
sFilter
 | A string specifying a filter to perform a more specific search.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether a file was found. If there were no files found the value will be 0.


sFTPFindNextFile

FTP Function Reference

sFTPFindNextFile

FTP Function Reference

This function searches for the next file after a call to the sFTPFindFirstFile.

Declare Function sFTPFindNextFile Lib "SapphireFTP.dll" (ByVal sFileString As String, ByVal lLicence As Long) As Long

Parameters

sFileString
 | A string variable that is used to return the details of the next file found.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether a file was found. If there were no files found the value will be 0.


sFTPCurrentDirectory

FTP Function Reference

sFTPCurrentDirectory

FTP Function Reference

This function retrieves the path of the current remote FTP directory.

Declare Function sFTPCurrentDirectory Lib "SapphireFTP.dll" (ByVal sCurrentDirectory As String, ByVal lLicence As Long) As Long

Parameters

sCurrentDirectory
 | A string variable that is used to store the name of the current remote FTP directory.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPChangeDirectory

FTP Function Reference

sFTPChangeDirectory

FTP Function Reference

This function changes to the specified directory on the remote server.

Declare Function sFTPChangeDirectory Lib "SapphireFTP.dll" (ByVal sPath As String, ByVal lLicence As Long) As Long

Parameters

sPath
 | A string specifying the absolute or relative path to the directory to change to.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPRemoveFile

FTP Function Reference

sFTPRemoveFile

FTP Function Reference

This function removes a file from the remote server.

Declare Function sFTPRemoveFile Lib "SapphireFTP.dll" (ByVal sRemoteFile As String, ByVal lLicence As Long) As Long

Parameters

sRemoteFile
 | A string specifying the name of the remote file to remove.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPRemoveDirectory

FTP Function Reference

sFTPRemoveDirectory

FTP Function Reference

This function removes a directory on the remote server.

Declare Function sFTPRemoveDirectory Lib "SapphireFTP.dll" (ByVal sDirectory As String, ByVal lLicence As Long) As Long

Parameters

sDirectory
 | A string specifying the remote directory to remove.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.

Remarks

The function will only remove if there are 10 or less sub directories per child directory node.


sFTPRenameFile

FTP Function Reference

sFTPRenameFile

FTP Function Reference

This function renames a remote file or directory in the current path on the remote server.

Declare Function sFTPRenameFile Lib "SapphireFTP.dll" (ByVal sOldFile As String, ByVal sNewFile As String, ByVal lLicence As Long) As Long

Parameters

sOldFile
 | A string specifying the remote file or directory to rename.
sNewFile
 | A string specifying the remote file or directory to rename to.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPMakeDirectory

FTP Function Reference

sFTPMakeDirectory

FTP Function Reference

This function creates a directory in the current path on the remote server.

Declare Function sFTPMakeDirectory Lib "SapphireFTP.dll" (ByVal sDirectory As String, ByVal lLicence As Long) As Long

Parameters

sDirectory
 | A string specifying the remote directory to create.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure. If the operation was successful then the return value will be FTP_NO_ERROR. Use sFTPErrorText to get a string version of the error message.


sFTPFileExists

FTP Function Reference

sFTPFileExists

FTP Function Reference

This function checks to see if a file or directory exists on the remote server.

Declare Function sFTPFileExists Lib "SapphireFTP.dll" (ByVal sFile As String, ByVal lLicence As Long) As Long

Parameters

sFile
 | A string specifying the name of the file or directory to see if it exists.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether the file exists or not where 1 means the file exists and 0 means it does not.

Remarks

You cannot call sFTPFileExists between calls to sFTPFindFirstFile and sFTPFindNextFile. Calling sFTPFileExists close all previous file searches.


sFTPErrorText

FTP Function Reference

sFTPErrorText

FTP Function Reference

This routine retrieves a text version of an error number returned from a previous function.

Declare Sub sFTPErrorText Lib "SapphireFTP.dll" (ByVal sErrorText As String, ByVal lError As Long)

Parameters

sErrorText
 | A string variable that will be used to store the text description of the error. If the error number is not recognised then it will return 'unknown error' and the system error number.
lError
 | A long specifying number of the error to lookup.

Return Values

None


sFTPReconnect

FTP Function Reference

sFTPReconnect

FTP Function Reference

This function reestablishes a connection to the remote server to ensure that the correct information is retrieved from the remote server.

Declare Function sFTPReconnect Lib "SapphireFTP.dll" (ByVal lPassive As Long, ByVal lLicence As Long) As Long

Parameters

lPassive
 | A long flag specifying whether to use passive mode or not. Setting this parameter to 1 will use passive mode and setting to 0 will use active mode.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating whether the reconnect procedure was successful or not. 1 = Successful, 0 = Failed.


Error Codes

FTP Error Codes

Error Codes

FTP Function Reference

The following is a list of error codes that are defined in your eVB project.

Public Const FTP_NO_ERROR = 0
Public Const FTP_TOO_MANY_INTERNET_HANDLES = 1
Public Const FTP_TIMEOUT = 2
Public Const FTP_INTERNAL_ERROR = 3
Public Const FTP_INVALID_URL = 4
Public Const FTP_NAME_NOT_RESOLVED = 5
Public Const FTP_PROTOCOL_NOT_FOUND = 6
Public Const FTP_SHUTDOWN = 7
Public Const FTP_INCORRECT_USER_NAME = 8
Public Const FTP_INCORRECT_PASSWORD = 9
Public Const FTP_LOGIN_FAILED = 10
Public Const FTP_REQUEST_PENDING = 11
Public Const FTP_CANNOT_CONNECT = 12
Public Const FTP_CONNECTION_ABORTED = 13
Public Const FTP_CONNECTION_RESET = 14
Public Const FTP_FORCE_RETRY = 15
Public Const FTP_INVALID_PROXY_REQUEST = 16
Public Const FTP_TRANSFER_IN_PROGRESS = 17
Public Const FTP_DROPPED = 18
Public Const FTP_NO_PASSIVE_MODE = 19
Public Const FTP_LOCAL_FILE_EXISTS = 20
Public Const FTP_UNKNOWN = 21


Parameter Codes

FTP Parameter Codes

Parameter Codes

FTP Function Reference

The following is a list of parameter codes that are defined in your eVB project.

' Overwrite modes
Public Const FTP_OVERWRITE = 1
Public Const FTP_DONT_OVERWRITE = 0

' Transfer modes
Public Const FTP_TRANSFER_UNKNOWN = 0
Public Const FTP_TRANSFER_ASCII = 1
Public Const FTP_TRANSFER_BINARY = 2

Public Const DEFAULT_FTP_PORT = 21


Sapphire IrDA Utility

Sapphire IrDA Utility Contents

The Sapphire IrDA Utility is designed for printing to an Infra-red enabled printer using the IrDA port on your device. This document is for version 3.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire IrDA Utility is designed for eVB and VB.NET developers allowing an application to print text to a printer via the IrDA port. The utility is capable of doing the following:

  • Establish a connection with an IrDA enabled printer
  • Print text to the printer
  • Print new lines and form feeds
  • Send escape codes to add functionality
  • Close the connection with the printer

Version History

v3.0 | Added support for graphics printing depending on printer specification
v2.0 | VB.NET Compatible
v1.0 | Initial development of the utility


Supported Hardware

The current supported hardware for the Sapphire IrDA Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HDT600-SH4
  • HPC Pro2.11-ARM
  • HPC Pro2.11-MIPS
  • HPC Pro2.11-SH3
  • HPC Pro2.11-SH4
  • HPC Pro2.11-X86-Emulator
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Palm Size PC 2.11-MIPS
  • Palm Size PC 2.11-SH3
  • Palm Size PC 2.11-X86-Emulator
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire IrDA Utility comes with a demo project that shows how print using the IrDA port. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

IrDA Print Demo Application


IrDA Print Demo Application

The IrDA Print Demo Application shows how to print text using the Sapphire IrDA Utility.

Simply enter a simple text line that you wish to print in the text box. You can specify a few options such as Include form feed, Double Width Text, Underline Text and Bold Text. When you are ready to print, press the Print button.

Pressing the Close button will exit the demo application.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

prnConnect | Connects to an IrDA printer
prnClosePrinter | Closes a printer connection
prnPrintLine | Prints a text string
prnNewLine | Prints a new line
prnFormFeed | Performs a form feed

Example Code

Click here to view example code


prnConnect

IrDA Function Reference

prnConnect

IrDA Function Reference | Example

This function connects to an IrDA printer.

<DllImport("SapphireIRDA.dll")> _
Public Function prnConnect(ByVal lLicence As Integer) As Integer
End Function

Parameters

lLicence
An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


prnClosePrinter

IrDA Function Reference

prnClosePrinter

IrDA Function Reference | Example

This function closes a printer connection.

<DllImport("SapphireIRDA.dll")> _
Public Function prnClosePrinter() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


prnPrintLine

IrDA Function Reference

prnPrintLine

IrDA Function Reference | Example

This function sends a text string to the printer.

<DllImport("SapphireIRDA.dll")> _
Public Function prnPrintLine(ByVal sData As String, ByVal lLen as Integer) As Integer
End Function

Parameters

sData
 | This is a string that contains the data to print.
lLen
 | An integer specifying the length of the data source.

Return Values

Returns a number indicating success or failure where 0 is successful.

Remarks

It is possible to send escape codes to your printer using the Chr() function.

Examples:

Double width text
prnPrintLine(Chr(14))

Underline text
prnPrintLine(Chr(27) & Chr(45) & Chr(1))

Bold text
prnPrintLine(Chr(27) & "E")


prnNewLine

IrDA Function Reference

prnNewLine

IrDA Function Reference | Example

This function prints a new line on the printer.

<DllImport("SapphireIRDA.dll")> _
Public Function prnNewLine() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


prnFormFeed

IrDA Function Reference

prnFormFeed

IrDA Function Reference | Example

This function tells the printer to perform a form feed.

<DllImport("SapphireIRDA.dll")> _
Public Function prnFormFeed() As Integer
End Function

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

IrDA Example Code

Example Code

IrDA Function Reference

The following example shows how to connect to a printer, print some text and then close the printer connection.

Private Function PrinterTest() As Byte
Dim bPrinterRetry As Boolean

PrinterTest = 1

bPrinterRetry = True
While bPrinterRetry
' Connect to the printer
If (prnConnect(1234567890) = 0) Then
' Start printing the text
If (prnPrintLine("Test print using the SapphireIRDA DLL") <> 0) Then Exit Function
If (prnNewLine() <> 0) Then Exit Function
If (prnPrintLine("Purchase online at www.sapphire-solutions.co.uk for commercial version") <> 0) Then Exit Function

If (prnFormFeed() <> 0) Then Exit Function

If (prnClosePrinter() <> 0) Then
MsgBox("Unable to close printer port", vbOKOnly, "SapphireIRDA Print Demo")
End If

PrinterTest = 0

bPrinterRetry = False
Else
If MsgBox("Unable to locate printer, plese ensure the IrDA ports are aligned.", vbRetryCancel, "SapphireIRDA Print Demo") = vbCancel Then
bPrinterRetry = False
PrinterTest = 2
End If
End If
Wend
End Function


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

prnConnect | Connects to an IrDA printer
prnClosePrinter | Closes a printer connection
prnPrintLine | Prints a text string
prnNewLine | Prints a new line
prnFormFeed | Performs a form feed

Example Code

Click here to view example code


prnConnect

IrDA Function Reference

prnConnect

IrDA Function Reference | Example

This function connects to an IrDA printer.

Declare Function prnConnect Lib "SapphireIRDA.dll" (ByVal lLicence As Long) As Integer

Parameters

lLicence
A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


prnClosePrinter

IrDA Function Reference

prnClosePrinter

IrDA Function Reference | Example

This function closes a printer connection.

Declare Function prnClosePrinter Lib "SapphireIRDA.dll" () As Integer

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


prnPrintLine

IrDA Function Reference

prnPrintLine

IrDA Function Reference | Example

This function sends a text string to the printer.

Declare Function prnPrintLine Lib "SapphireIRDA.dll" (ByVal sData As String, ByVal lLen As Long) As Integer

Parameters

sData
 | This is a string that contains the data to print.
lLen
 | A long specifying the length of the data source.

Return Values

Returns a number indicating success or failure where 0 is successful.

Remarks

It is possible to send escape codes to your printer using the Chr() function.

Examples:

Double width text
prnPrintLine(Chr(14))

Underline text
prnPrintLine(Chr(27) & Chr(45) & Chr(1))

Bold text
prnPrintLine(Chr(27) & "E")


prnNewLine

IrDA Function Reference

prnNewLine

IrDA Function Reference | Example

This function prints a new line on the printer.

Declare Function prnNewLine Lib "SapphireIRDA.dll" () As Integer

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


prnFormFeed

IrDA Function Reference

prnFormFeed

IrDA Function Reference | Example

This function tells the printer to perform a form feed.

Declare Function prnFormFeed Lib "SapphireIRDA.dll" () As Integer

Parameters

None

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

IrDA Example Code

Example Code

IrDA Function Reference

The following example shows how to connect to a printer, print some text and then close the printer connection.

Private Function PrinterTest() As Byte
Dim bPrinterRetry As Boolean

PrinterTest = 1

bPrinterRetry = True
While bPrinterRetry
' Connect to the printer
If (prnConnect(1234567890) = 0) Then
' Start printing the text
If (prnPrintLine("Test print using the SapphireIRDA DLL") <> 0) Then Exit Function
If (prnNewLine() <> 0) Then Exit Function
If (prnPrintLine("Purchase online at www.sapphire-solutions.co.uk for commercial version") <> 0) Then Exit Function

If (prnFormFeed() <> 0) Then Exit Function

If (prnClosePrinter() <> 0) Then
MsgBox "Unable to close printer port", vbOKOnly, "SapphireIRDA Print Demo"
End If

PrinterTest = 0

bPrinterRetry = False
Else
If MsgBox("Unable to locate printer, plese ensure the IrDA ports are aligned.", vbRetryCancel, "SapphireIRDA Print Demo") = vbCancel Then
bPrinterRetry = False
PrinterTest = 2
End If
End If
Wend
End Function


Sapphire GZip Utility

Sapphire GZip Utility Contents

The Sapphire GZip Utility is designed for compressing and decompressing single GZip files along with Zip files. This document is for version 4.10 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire GZip Utility is designed for eVB and VB.NET developers allowing an application to compress and decompress any given file into a gzip or zip file format. The utility is capable of doing the following:

  • Compress a file into a gzip file
  • Decompress a gzip file
  • Compress multiple files into a zip file
  • Decompress selected files from a zip file

Version History

v4.10 | Allows unzipping all files to a different directory
v4.0 | VB.NET Compatible


Supported Hardware

The current supported hardware for the Sapphire GZip Utility are:

  • Dolphin7400-ARM
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • Smartphone-ARM
  • Smartphone-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire GZip Utility comes with a demo project that shows how compress and decompress single file .gz and multi-file .zip files. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

GZip Menu Screen
GZip .gz file compression/decompression
Zip file compression
Zip file decompression


GZip Menu Screen

This menu gives the options for the GZip functionality.

GZip .gz Demo
This demonstrates how to compress and decompress single files into the .gz file format.

Zipping .Zip Demo
This demonstrates how to compress files and directories into a .zip file format.

Unzipping .Zip Demo
This demonstrates how to decompress a zip file from the .zip format.

The Close button exits the demo application.


GZip .gz file compression/decompression

This demo shows how to compress and decompress using the GZip file format.

The two lists show the contents of the \My Documents folder on the device. The right right list only shows files with the .gz extension where the left list shows all other files.

To compress a file, simply select it on the left list and press the '>' button. To decompress a .gz file, select it on the right list and press the '<' button. To view the contents of a text file or BMP file, double-tap it in the list and it will be shown in the preview box below.

The Back button returns to the GZip menu.


Zip File Compression

This demo shows how to create a Zip file from a selection of files on the local device.

Simply specify the Zip File that you wish to create in the first text box. The second text box states the files you wish to add to the Zip file. This can either be a single file, and entire directory or a filtered search.

The Include Sub Directories option is used if you wish to include any child directories in the search for files to add to the zip file.

The Zip button performs the compression and the Back button returns to the GZip menu.


Zip File Decompression

This demo shows how to decompress a Zip file onto the local device.

Simply enter the Zip File name of the existing Zip file to decompress. The second text box allows the selection of files to decompress out of the zip file. This can either be a single file, an entire directory or a filtered search.

The Use Path Names option is used if you wish to use the directory information that is stored in the zip file when decompressing.

The UnZip button performs the decompression and the Back button returns to the GZip menu.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sGZip | Compress a file to a .gz file
sGUnzip | Decompress a .gz file
sZip | Create a .zip file
sUnzip | Decompress a .zip file

Example Code

Click here to view example code


sGZip

GZip Function Reference

sGZip

GZip Function Reference | Example

This routine compresses a single file into a .gz file.

<DllImport("SapphireGZip.dll")> _
Public Sub sGZip(ByVal sFileIn As String, ByVal sFileOut As String, ByVal lDelete As Integer, ByVal lLicence As Integer)
End Sub

Parameters

sFileIn
 | A string specifying the name of the file to compress.
sFileOut
 | A string specifying the name of the .gz file to create.
lDelete
 | An integer flag specifying whether to overwrite the destination file if it already exists. 1 is overwrite, 0 is don't overwrite.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

None


sGUnzip

GZip Function Reference

sGUnzip

GZip Function Reference | Example

This routine decompresses a .gz file.

<DllImport("SapphireGZip.dll")> _
Public Sub sGUnzip(ByVal sFileIn As String, ByVal sFileOut As String, ByVal lDelete As Integer, ByVal lLicence As Integer)
End Sub

Parameters

sFileIn
 | A string specifying the name of the file to decompress.
sFileOut
 | A string specifying the name of the file to create after decompression.
lDelete
 | An integer flag specifying whether to overwrite the destination file if it already exists. 1 is overwrite, 0 is don't overwrite.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

None


sZip

GZip Function Reference

sZip

GZip Function Reference | Example

This function creates a zip file.

<DllImport("SapphireGZip.dll")> _
Public Function sZip(ByVal sFileIn As String, ByVal sFileOut As String, ByVal lSubDirs As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sFileIn
 | A string specifying the name or pattern of the file(s) to compress.
sFileOut
 | A string specifying the name of the .zip file to create.
lSubDirs
 | An integer specifying whether to include sub directories in the compression.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


sUnzip

GZip Function Reference

sUnzip

GZip Function Reference | Example

This function decompresses a zip file.

<DllImport("SapphireGZip.dll")> _
Public Function sUnzip(ByVal sFileIn As String, ByVal sFileOut As String, ByVal lOverWrite As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sFileIn
 | A string specifying the name of the zip file to decompress.
sFileOut
 | A string specifying the name of the file to extract out of the zip file. If all files are to be extracted, this parameter should be an empty string. They will be extracted to the root directory. If you wish to specify a destination directory to extract all the files to, simply specify a he path, e.g. '\My Documents\".
lWithPath
 | An integer specifying whether to use the original path information in the zip file. 1 = Yes, 0 = No.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

GZip Example Code

Example Code

GZip Function Reference

The following examples show how to compress and decompress .gz and .zip files.

.gz file compression

sGZip("\My Documents\file.txt", "\My Documents\compressed.txt", 1, 1234567890)

.gz file decompression

sGUnzip("\My Documents\compressed.txt.gz", "\My Documents\file.txt", 1, 1234567890)

.zip file compression

Dim iResult As Integer

iResult = sZip("\My Documents\*.txt", "\My Documents\text.zip", 0, 1234567890)
If iResult <> 0 Then
MsgBox("Unable to compress files")
Else
MsgBox("Files have been compressed")
End If

.zip file decompression

Dim iResult As Integer

iResult = sUnzip("\My Documents\text.zip", "", 0, 1234567890)
If iResult <> 0 Then
Msgbox("Unable to decompress zip file")
Else
MsgBox("Files have been decompressed")
End If


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sGZip | Compress a file to a .gz file
sGUnzip | Decompress a .gz file
sZip | Create a .zip file
sUnzip | Decompress a .zip file

Example Code

Click here to view example code


sGZip

GZip Function Reference

sGZip

GZip Function Reference | Example

This function compresses a single file into a .gz file.

Declare Sub sGZip Lib "SapphireGZip.dll" (ByVal sFileIn As String, ByVal sFileOut As String, ByVal lDelete As Long, ByVal lLicence As Long)

Parameters

sFileIn
 | A string specifying the name of the file to compress.
sFileOut
 | A string specifying the name of the .gz file to create.
lDelete
 | A long flag specifying whether to overwrite the destination file if it already exists. 1 is overwrite, 0 is don't overwrite.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

None


sGUnzip

GZip Function Reference

sGUnzip

GZip Function Reference | Example

This function decompresses a .gz file.

Declare Sub sGUnzip Lib "SapphireGZip.dll" (ByVal sFileIn As String, ByVal sFileOut As String, ByVal lDelete As Long, ByVal lLicence As Long)

Parameters

sFileIn
 | A string specifying the name of the file to decompress.
sFileOut
 | A string specifying the name of the file to create after decompression.
lDelete
 | A long flag specifying whether to overwrite the destination file if it already exists. 1 is overwrite, 0 is don't overwrite.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

None


sZip

GZip Function Reference

sZip

GZip Function Reference | Example

This function creates a zip file.

Declare Function sZip Lib "SapphireGZip.dll" (ByVal sFileIn As String, ByVal sFileOut As String, ByVal lSubDirs As Long, ByVal lLicence As Long) As Long

Parameters

sFileIn
 | A string specifying the name or pattern of the file(s) to compress.
sFileOut
 | A string specifying the name of the .zip file to create.
lSubDirs
 | A long specifying whether to include sub directories in the compression.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


sUnzip

GZip Function Reference

sUnzip

GZip Function Reference | Example

This function decompresses a zip file.

Declare Function sUnzip Lib "SapphireGZip.dll" (ByVal sFileIn As String, ByVal sFileOut As String, ByVal lWithPath As Long, ByVal lLicence As Long) As Long

Parameters

sFileIn
 | A string specifying the name of the zip file to decompress.
sFileOut
 | A string specifying the name of the file to extract out of the zip file. If all files are to be extracted, this parameter should be an empty string. They will be extracted to the root directory. If you wish to specify a destination directory to extract all the files to, simply specify a he path, e.g. '\My Documents\".
lWithPath
 | A long specifying whether to use the original path information in the zip file. 1 = Yes, 0 = No.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

GZip Example Code

Example Code

GZip Function Reference

The following examples show how to compress and decompress .gz and .zip files.

.gz file compression

sGZip "\My Documents\file.txt", "\My Documents\compressed.txt", 1, 1234567890

.gz file decompression

sGUnzip "\My Documents\compressed.txt.gz", "\My Documents\file.txt", 1, 1234567890

.zip file compression

Dim lResult As Long

lResult = sZip("\My Documents\*.txt", "\My Documents\text.zip", 0, 1234567890)
If lResult <> 0 Then
MsgBox "Unable to compress files"
Else
MsgBox "Files have been compressed"
End If

.zip file decompression

Dim lResult As Long

lResult = sUnzip("\My Documents\text.zip", "", 0, 1234567890)
If lResult <> 0 Then
Msgbox "Unable to decompress zip file"
Else
MsgBox "Files have been decompressed"
End If


Sapphire Encrypt Utility

Sapphire Encrypt Utility Contents

The Sapphire Encrypt Utility is designed for encrypting and decrypting data files and text strings. This document is for version 4.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Encrypt

Release Notes

The Sapphire Encrypt Utility is designed for eVB and VB.NET developers allowing an application to encrypt or decrypt a given file or text using symmetric encryption provided by the RC2 40-bit key algorithm. The utility uses the Microsoft CryptoAPI functionality and a 40-bit encryption key algorithm gives over one trillion possible decryption keys. The utility is capable of doing the following:

  • Encrypt a file with a given key
  • Decrypt a file specifying a key
  • Encrypt a text string with a given key
  • Decrypt a text string specifying a key

Version History

v4.0 VB.NET Compatible


Supported Hardware

The current supported hardware for the Sapphire Encrypt Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86
  • Windows32

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire Encrypt Utility comes with a demo project that shows how encrypt and decrypt files and text strings. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

Encrypt Menu Screen
File Encryption
File Decryption
String Encryption and Decryption


Encrypt Menu Screen

This menu gives the options for the Encrypt functionality.

Encrypt File
This demonstrates how to encrypt a file from a given key.

Decrypt File
This demonstrates how to decrypt a file using a key.

Encrypt Text
This demonstrates how to encrypt and decrypt a text string.

The Close button exits the demo application.


File Encryption

This form shows how to encrypt a file based on a given key.

Password refers to the key that will be used to encrypt the file with.
Original is the file on the local device that will be encrypted.
Encrypted is a file that will be created with the encrypted content.

The Encrypt button performs the encryption and the Back button returns to the Encrypt menu.


File Decryption

This form shows how to decrypt a file using the original key that encrypted it.

Password refers to the key that was used when the file was encrypted.
Encrypted is the encrypted file on the local device that will be decrypted.
Decrypted is a file that will be created with the non-encrypted content.

The Decrypt button performs the decryption and the Back button returns to the Encrypt menu.


String Encryption and Decryption

This form shows how to encrypt and decrypt a text string using a specified key.

Password refers to the key to use when encrypting and decrypting.
Original is the plain text string to encrypt.
Encrypted is the encrypted content after encryption.
Decrypted is the decrypted content after decryption based on the encrypted text and key.

The Encrypt button encrypts the original text using the password and places the result in the encrypted field.

The Decrypt button decrypted the encrypted text using the password and places the result in the decrypted field.

The Back button returns to the Encrypt menu.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sEncryptText | Encrypt a text string
sDecryptText | Decrypt a text string
sEncryptFile | Encrypt a file
sDecryptFile | Decrypt a file

Example Code

Click here to view example code


sEncryptText

Encrypt Function Reference

sEncryptText

Encrypt Function Reference | Example

This function encrypts a text string based on a given key.

<DllImport("SapphireEncrypt.dll")> _
Public Function sEncryptText(ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Integer, ByVal bMessages As Byte) As Integer
End Function

Parameters

sSource
 | A string specifying the plain text to encrypt.
sDestination
 | A variable to store the encrypted text into.
sKey
 | A string specifying the key to use when encrypting. This may be considered as a password.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sDecryptText

Encrypt Function Reference

sDecryptText

Encrypt Function Reference | Example

This function decrypts a text string based on a given key.

<DllImport("SapphireEncrypt.dll")> _
Public Function sDecryptText(ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Integer, ByVal bMessages As Byte) As Integer
End Function

Parameters

sSource
 | A string specifying the encrypted text to decrypt.
sDestination
 | A variable to store the decrypted text into.
sKey
 | A string specifying the key that was used to encrypt the text. This may be considered as a password.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sEncryptFile

Encrypt Function Reference

sEncryptFile

Encrypt Function Reference | Example

This function encrypts a file based on a given key.

<DllImport("SapphireEncrypt.dll")> _
Public Function sEncryptFile(ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Integer, ByVal bMessages As Byte) As Integer
End Function

Parameters

sSource
 | A string specifying the name of the file to encrypt.
sDestination
 | A string specifying the name of the file to create with the encrypted content.
sKey
 | A string specifying the key to use to encrypt the file. This may be considered as a password.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sDecryptFile

Encrypt Function Reference

sDecryptFile

Encrypt Function Reference | Example

This function decrypts a file based on a given key.

<DllImport("SapphireEncrypt.dll")> _
Public Function sDecryptFile(ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Integer, ByVal bMessages As Byte) As Integer
End Function

Parameters

sSource
 | A string specifying the name of the encrypted file to dencrypt.
sDestination
 | A string specifying the name of the file to create with the decrypted content.
sKey
 | A string specifying the key that was used to encrypt the file. This may be considered as a password.
lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

Encrypt Example Code

Example Code

Encrypt Function Reference

The following examples show how to encrypt and decrypt files and text.

Text encryption and decryption

Dim iResult As Integer
Dim sEncrypted As String
Dim sDecrypted As String

' Fill sNew to force the string variable to a sufficient size for the returned string (Max 1000)
sEncrypted = Space(1000)

' Encrypt the text
iResult = sEncryptText("Test to encrypt", sEncrypted, "password", 1234567890, True)
If iResult = 0 Then
MsgBox("Text has been encrypted to '" & sEncrypted & "'")
Else
MsgBox("Unable to encrypt text")
End If

' Decrypt the text
sDecrypted = Space(1000)
i Result = sDecryptText(sEncrypted, sDecrypted, "password", 1234567890, True)
If iResult = 0 Then
MsgBox("Text has been decrypted to '" & sDecrypted & "'")
Else
MsgBox("Unable to decrypt text")
End If

File encryption and decryption

Dim iResult As Integer

' Encrypt a file
iResult = sEncryptFile("\My Documents\plain.txt", "\My Documents\cipher.txt", "password", 1234567890, True)
If iResult = 0 Then
MsgBox("The file has been encrypted")
Else
MsgBox("Unable to encrypt file")
End If

' Decrypt a file
iResult = sDecryptFile("\My Documents\cipher.txt", "\My Documents\decrypted.txt", "password", 1234567890, True)
If iResult = 0 Then
MsgBox("The file has been decrypted")
Else
MsgBox("Unable to decrypt file")
End If


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sEncryptText | Encrypt a text string
sDecryptText | Decrypt a text string
sEncryptFile | Encrypt a file
sDecryptFile | Decrypt a file

Example Code

Click here to view example code


sEncryptText

Encrypt Function Reference

sEncryptText

Encrypt Function Reference | Example

This function encrypts a text string based on a given key.

Declare Function sEncryptText Lib "SapphireEncrypt.dll" (ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Long, ByVal bMessages As Byte) As Long

Parameters

sSource
 | A string specifying the plain text to encrypt.
sDestination
 | A variable to store the encrypted text into.
sKey
 | A string specifying the key to use when encrypting. This may be considered as a password.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sDecryptText

Encrypt Function Reference

sDecryptText

Encrypt Function Reference | Example

This function decrypts a text string based on a given key.

Declare Function sDecryptText Lib "SapphireEncrypt.dll" (ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Long, ByVal bMessages As Byte) As Long

Parameters

sSource
 | A string specifying the encrypted text to decrypt.
sDestination
 | A variable to store the decrypted text into.
sKey
 | A string specifying the key that was used to encrypt the text. This may be considered as a password.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sEncryptFile

Encrypt Function Reference

sEncryptFile

Encrypt Function Reference | Example

This function encrypts a file based on a given key.

Declare Function sEncryptFile Lib "SapphireEncrypt.dll" (ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Long, ByVal bMessages As Byte) As Long

Parameters

sSource
 | A string specifying the name of the file to encrypt.
sDestination
 | A string specifying the name of the file to create with the encrypted content.
sKey
 | A string specifying the key to use to encrypt the file. This may be considered as a password.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


sDecryptFile

Encrypt Function Reference

sDecryptFile

Encrypt Function Reference | Example

This function decrypts a file based on a given key.

Declare Function sDecryptFile Lib "SapphireEncrypt.dll" (ByVal sSource As String, ByVal sDestination As String, ByVal sKey As String, ByVal lLicence As Long, ByVal bMessages As Byte) As Long

Parameters

sSource
 | A string specifying the name of the encrypted file to dencrypt.
sDestination
 | A string specifying the name of the file to create with the decrypted content.
sKey
 | A string specifying the key that was used to encrypt the file. This may be considered as a password.
lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
bMessages
 | A byte flag stating whether to allow the utility to report to the user any messages.

Return Values

Returns a number indicating success or failure where 0 is successful.


Example Code

Encrypt Example Code

Example Code

Encrypt Function Reference

The following examples show how to encrypt and decrypt files and text.

Text encryption and decryption

Dim lResult As Long
Dim sEncrypted As String
Dim sDecrypted As String

' Fill sNew to force the string variable to a sufficient size for the returned string (Max 1000)
sEncrypted = Space(1000)

' Encrypt the text
lResult = sEncryptText("Test to encrypt", sEncrypted, "password", 1234567890, True)
If lResult = 0 Then
MsgBox "Text has been encrypted to '" & sEncrypted & "'"
Else
MsgBox "Unable to encrypt text"
End If

' Decrypt the text
sDecrypted = Space(1000)
lResult = sDecryptText(sEncrypted, sDecrypted, "password", 1234567890, True)
If lResult = 0 Then
MsgBox "Text has been decrypted to '" & sDecrypted & "'"
Else
MsgBox "Unable to decrypt text"
End If

File encryption and decryption

Dim lResult As Long

' Encrypt a file
lResult = sEncryptFile("\My Documents\plain.txt", "\My Documents\cipher.txt", "password", 1234567890, True)
If lResult = 0 Then
MsgBox "The file has been encrypted"
Else
MsgBox "Unable to encrypt file"
End If

' Decrypt a file
lResult = sDecryptFile("\My Documents\cipher.txt", "\My Documents\decrypted.txt", "password", 1234567890, True)
If lResult = 0 Then
MsgBox "The file has been decrypted"
Else
MsgBox "Unable to decrypt file"
End If


Sapphire Buttons Utility

Sapphire Buttons Utility Contents

The Sapphire Buttons Utility is designed for detecting different button presses on the hardware keys of the device. This document is for version 2.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire Buttons Utility is designed for eVB and VB.NET developers allowing an application to detect hardware buttons being pressed on the device.

Version History

v2.0 | Added the functionality to enable or disable specific button assignments
v1.0 | VB.NET Compatible Initial release of Sapphire Buttons


Supported Hardware

The current supported hardware for the Sapphire Buttons Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HPC Pro2.11-ARM
  • HPC Pro2.11-MIPS
  • HPC Pro2.11-SH3
  • HPC Pro2.11-SH4
  • HPC Pro2.11-X86-Emulator
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Palm Size PC 2.11-MIPS
  • Palm Size PC 2.11-SH3
  • Palm Size PC 2.11-X86-Emulator
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire Button Utility comes with a demo project that shows how monitor for button presses made by the user on the device. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.

Buttons Demo Application


Buttons Demo Application

This demo shows how to monitor for button presses made by the user on the device.

The Current Button Pressed frame shows the current button that is being pressed but hasn't been released by the user.

The Previous Buttons Pressed frame shows the last 7 buttons that were pressed by the user.

The Close button exits the Buttons demo.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sButtons | Retrieves the last button pressed
sButtonName | Retrieves the text name of the button
sButtonAssignment | Enables or disables a button assignment.

Example Code

Click here to view example code


sButtons

Buttons Function Reference

sButtons

Buttons Function Reference | Example

This function returns the associated numbers for the button that has been pressed on the device.

<DllImport("SapphireButtons.dll")> _
Public Function sButtons(ByVal lLicence As Integer, ByRef lKey1 As Integer, ByRef lKey2 As Integer) As Integer
End Function

Parameters

lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
lKey1
 | An integer that stores the first button number.
lKey2
 | An integer that stores the second button number.

Return Values

Returns a number indicating whether a button has been pressed, 0 indicates that no button was pressed.

Remarks

The reason for having two key values for the button number is because some buttons are identified by only one number whereas other require two.


sButtonName

Buttons Function Reference

sButtonName

Buttons Function Reference | Example

This function returns the name of the specified button.

<DllImport("SapphireButtons.dll")> _
Public Sub sButtonName(ByVal sButtonText As String, ByVal lButtonNumber As Integer)
End Sub

Parameters

sButtonText
 | A string variable that will be used to store the name of the button.
lButtonNumber
 | An integer specifying which button to retrieve the name for.

Return Values

None


sButtonAssignment

Buttons Function Reference

sButtonAssignment

Buttons Function Reference | Example

This function enables or disables a button assignment.

<DllImport("SapphireButtons.dll")> _
Public Function sButtonAssignment(ByVal lLicence As Integer, ByVal sButtonID As String, ByVal lButtonEnable As Integer) As Integer
End Function

Parameters

lLicence
 | An integer specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
sButtonID
 | A string specifying the button to enable/disable.
lButtonEnable
 | An integer specifying whether to enable or disable the button assignment. 1 = Enable, 0 = Disable.

Return Values

Return value not used.

Remarks

None


Example Code

Buttons Example Code

Example Code

Buttons Function Reference

The following example shows how get the last button pressed and retrieve its name.

Private Sub tmrButtons_Tick(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles tmrButtons.Tick
Dim lButton As Integer
Dim lKey1 As Integer
Dim lKey2 As Integer

lButton = sButtons(1234567890, lKey1, lKey2)

If lButton = 0 Then
lblButton.Text = ""
Else
If lKey2 = 0 Then
lblButton.Text = ButtonName(lKey1)
Else
lblButton.Text = ButtonName(lKey1) & " (" & ButtonName(lKey2) & ")"
End If
End If
End Sub

Public Function ButtonName(iButton As Integer) As String
Dim sName As String = Space(1024)
sButtonName(sName, iButton)
ButtonName = StripString(sName)
End Function

Public Function StripString(sSource As String) As String
Dim lEnd As Long

lEnd = InStr(sSource, Chr(0))
If lEnd > 0 Then
StripString = Mid(sSource, 1, lEnd - 1)
Else
StripString = sSource
End If
End Function


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sButtons | Retrieves the last button pressed
sButtonName | Retrieves the text name of the button
sButtonAssignment | Enables or disables a button assignment.

Example Code

Click here to view example code


sButtons

Buttons Function Reference

sButtons

Buttons Function Reference | Example

This function returns the associated numbers for the button that has been pressed on the device.

Declare Function sButtons Lib "SapphireButtons.dll" (ByVal lLicence As Long, ByRef lKey1 As Long, ByRef lKey2 As Long) As Long

Parameters

lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
lKey1
 | A long that stores the first button number.
lKey2
 | A long that stores the second button number.

Return Values

Returns a number indicating whether a button has been pressed, 0 indicates that no button was pressed.

Remarks

The reason for having two key values for the button number is because some buttons are identified by only one number whereas other require two.


sButtonName

Buttons Function Reference

sButtonName

Buttons Function Reference | Example

This function returns the name of the specified button.

Declare Sub sButtonName Lib "SapphireButtons.dll" (ByVal sButtonText As String, ByVal lButtonNumber As Long)

Parameters

sButtonText
 | A string variable that will be used to store the name of the button.
lButtonNumber
 | A long specifying which button to retrieve the name for.

Return Values

None


sButtonAssignment

Buttons Function Reference

sButtonAssignment

Buttons Function Reference | Example

This function enables or disables a button assignment.

Declare Sub sButtonAssignmentLib "SapphireButtons.dll" (ByVal lLicence As Long, ByVal sButtonID As String, ByVal lButtonEnable As Long)

Parameters

lLicence
 | A long specifying the licence number of the registered utility. If using in demo mode, enter 1234567890.
sButtonID
 | A string specifying the button to enable/disable.
lButtonEnable
 | A long specifying whether to enable or disable the button assignment. 1 = Enable, 0 = Disable.

Return Values

None


Example Code

Buttons Example Code

Example Code

Buttons Function Reference

The following example shows how get the last button pressed and retrieve its name.

Private Sub tmrButtons_Timer()
Dim lButton As Long
Dim lKey1 As Long
Dim lKey2 As Long

lButton = sButtons(1234567890, lKey1, lKey2)

If lButton = 0 Then
lblButton.Caption = ""
Else
If lKey2 = 0 Then
lblButton.Caption = ButtonName(lKey1)
Else
lblButton.Caption = ButtonName(lKey1) & " (" & ButtonName(lKey2) & ")"
End If
End If
End Sub

Public Function ButtonName(iButton As Integer) As String
Dim sName As String
sName = Space(25)
sButtonName sName, iButton
ButtonName = StripString(sName)
End Function

Public Function StripString(sSource As String) As String
Dim lEnd As Long

lEnd = InStr(sSource, Chr(0))
If lEnd > 0 Then
StripString = Mid(sSource, 1, lEnd - 1)
Else
StripString = sSource
End If
End Function


Sapphire Mail Utility

Sapphire Mail Utility Contents

The Sapphire Mail Utility is designed for creating and reading emails that are compatible with the Pocket PC's Inbox. This document is for version 1.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire Mail Utility is designed for creating and reading emails that are compatible with the Pocket PC's Inbox.

Version History

v1.0 VB.NET and eVB Compatible
Initial release of Sapphire Mail


Supported Hardware

The current supported hardware for the Sapphire Mail Utility are:

  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Smartphone 2003-ARM-XScale
  • Smartphone 2003-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire Mail Utility comes with a demo project that shows how monitor for button presses made by the user on the device. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

AddMailAccount | Adds a new mail account to the device's Inbox
sListServices | Lists the different mail accounts available on the device
sCreateMail | Creates a new email
sListMail | Lists the emails currently in the accounts Inbox
sReadMail | Retrieves the email header and body
sGetAttachementName | Retrieves the attachment name in an email
sSaveAttachment | Saves an attachment to a file.


AddMailAccount

Mail Function Reference

AddMailAccount

Mail Function Reference

This function create a new mail account on the device.

<DllImport("SapphireMail.dll")> _
Public Function AddMailAccount(ByVal lType As Integer, ByVal sMailAccount As String, _
ByVal sMailServer As String, ByVal sUserName As String, ByVal sPassword As String, _
ByVal sSmtpHost As String, ByVal sReturnAddress As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

lType
 | An integer specifying what type of mail account to add. 0 = POP3, 1 = IMAP.
sMailAccount
 | A string specifying the name of the account.
sMailServer
 | A string specifying the POP3 mail server address.
sUserName
 | A string specifying the email account user name.
sPassword
 | A string specifying the email account password.
sSmtpHost
 | A string specifying the SMTP mail server address.
sReturnAddress
 | A string specifying the return email address for the acocunt.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

Zero indicates success. Non-zero indicates failure.


sCreateMail

Mail Function Reference

sCreateMail

Mail Function Reference

This function create a new email.

<DllImport("SapphireMail.dll")> _
Public Function sCreateMail(ByVal sTo As String, ByVal sCc As String, _
ByVal sBcc As String, ByVal sSubject As String, ByVal sBody As String, ByVal sAttach As String, _
ByVal sService As String, ByVal lFolder As Integer, ByVal lLicence As Integer) As Integer
End Function

Parameters

sTo
 | A string specifying the email address of the main recipient.
sCC
 | A string specifying the email address of the carbon copy recipient.
sBcc
 | A string specifying the email address of the blink carbon copy recipient.
sSubject
 | A string specifying the email's subject.
sBody
 | A string specifying the message body of the email.
sAttach
 | A string specifying the filename of the file to attach.
sService
 | A string specifying the mail account to use.
lFolder
 | An integer specifying the folder to save the email to. 1 = Outbox, 0 = Drafts.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

Zero indicates success. Non-zero indicates failure.


sGetAttachmentName

Mail Function Reference

sGetAttachmentName

Mail Function Reference

This function retrieves the name of the attachment in the email.

<DllImport("SapphireMail.dll")> _
Public Function sGetAttachmentName(ByVal sService As String, ByVal lFolder As Integer, _
ByVal lReadEntry As Integer, ByVal sAttachment As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sService
 | A string representing the name of the mail account to lookup from.
lFolder
 | An Integer representing the folder to retrieve the email from. 1 = Inbox, 0 = Drafts.
lReadEntry
 | An Integer representing the index of the email to read the attachment name from.
sAttachment
 | A string variable used to store the returned attachment name.
lLicence
 | An Integer specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sListMail

Mail Function Reference

sListMail

Mail Function Reference

This function returns the list of email in the specified folder.

<DllImport("SapphireMail.dll")> _
Public Function sListMail(ByVal sService As String, ByVal lFolder As Integer, _
ByRef lEntries As Integer, ByVal sSubjects As String, ByVal sAttachFlags As String, _
ByVal sReadFlags As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sService
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | An integer specifying the folder to use. 1 = Inbox, 0 = Drafts.
lEntries
 | An integer variable used to return the number of emails returned.
sSubjects
 | A string variable used to return the email subjects. Each subject is seperated by the bar (|) character.
sAttachFlags
 | A string variable used to return whether the emails have attachments, seperated by the bar (|) character.
sReadFlags
 | A string variable used to return whether the emails have been read, seperated by the bar (|) character.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sListServices

Mail Function Reference

sListServices

Mail Function Reference

This function returns the list of mail accounts existing on the device.

<DllImport("SapphireMail.dll")> _
Public Function sListServices(ByRef lEntries As Integer, ByVal sServices As String, _
ByVal lLicence As Integer) As Integer
End Function

Parameters

lEntries
 | An integer variable used to store the number of services on the device.
sServices
 | A string variable used to store the list of services seperated by the '|' character.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sReadMail

Mail Function Reference

sReadMail

Mail Function Reference

This function retrieves the email information and body.

<DllImport("SapphireMail.dll")> _
Public Function sReadMail(ByVal sService As String, ByVal lFolder As Integer, _
ByVal lReadEntry As Integer, ByVal sSenderName As String, ByVal sSenderEmail As String, _
ByVal sSubject As String, ByRef lAttachment As Integer, ByVal sBody As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sService
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | An integer specifying the folder to use. 1 = Inbox, 0 = Drafts.
lReadEntry
 | An integer specifying the index of the email to read.
sSenderName
 | A string used to return the sender's name.
sSenderEmail
 | A string used to return the sender's email address.
sSubject
 | A string used to return the email's subject.
lAttachment
 | An integer used to return whether the email has an attachment or not. 1 = Yes, 0 = No.
sBody
 | A string used to return the email's body.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sSaveAttachment

Mail Function Reference

sSaveAttachment

Mail Function Reference

This function saves an attachment to file.

<DllImport("SapphireMail.dll")> _
Public Function sSaveAttachment(ByVal sService As String, ByVal lFolder As Integer, _
ByVal lReadEntry As Integer, ByVal sAttachment As String, ByVal lLicence As Integer) As Integer
End Function

Parameters

sServer
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | An integer specifying the folder to use. 1 = Inbox, 0 = Drafts.
lReadEntry
 | An integer specifying the index of the email to read.
sAttachment
 | A string specifying the destination location and filename of the attachment.
lLicence
 | An integer specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

AddMailAccount | Adds a new mail account to the device's Inbox
sListServices | Lists the different mail accounts available on the device
sCreateMail | Creates a new email
sListMail | Lists the emails currently in the accounts Inbox
sReadMail | Retrieves the email header and body
sGetAttachementName | Retrieves the attachment name in an email
sSaveAttachment | Saves an attachment to a file.


AddMailAccount

Mail Function Reference

AddMailAccount

Mail Function Reference

This function create a new mail account on the device.

Declare Function AddMailAccount Lib "SapphireMail.dll" ( _
ByVal lType As Long, _
ByVal sMailAccount As String, _
ByVal sMailServer As String, _
ByVal sUserName As String, _
ByVal sPassword As String, _
ByVal sSmtpHost As String, _
ByVal sReturnAddress As String, _
ByVal lLicence As Long) As Long

Parameters

lType
 | A long specifying what type of mail account to add. 0 = POP3, 1 = IMAP.
sMailAccount
 | A string specifying the name of the account.
sMailServer
 | A string specifying the POP3 mail server address.
sUserName
 | A string specifying the email account user name.
sPassword
 | A string specifying the email account password.
sSmtpHost
 | A string specifying the SMTP mail server address.
sReturnAddress
 | A string specifying the return email address for the acocunt.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

Zero indicates success. Non-zero indicates failure.


sCreateMail

Mail Function Reference

sCreateMail

Mail Function Reference

This function create a new email.

Declare Function sCreateMail Lib "SapphireMail.dll" (_
ByVal sTo As String, _
ByVal sCc As String, _
ByVal sBcc As String, _
ByVal sSubject As String, _
ByVal sBody As String, _
ByVal sAttach As String, _
ByVal sService As String, _
ByVal lFolder As Long, _
ByVal lLicence As Long) As Long

Parameters

sTo
 | A string specifying the email address of the main recipient.
sCC
 | A string specifying the email address of the carbon copy recipient.
sBcc
 | A string specifying the email address of the blink carbon copy recipient.
sSubject
 | A string specifying the email's subject.
sBody
 | A string specifying the message body of the email.
sAttach
 | A string specifying the filename of the file to attach.
sService
 | A string specifying the mail account to use.
lFolder
 | A long specifying the folder to save the email to. 1 = Outbox, 0 = Drafts.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

Zero indicates success. Non-zero indicates failure.


sGetAttachmentName

Mail Function Reference

sGetAttachmentName

Mail Function Reference

This function retrieves the name of the attachment in the email.

Declare Function sGetAttachmentName Lib "SapphireMail.dll" ( _
ByVal sService As String, _
ByVal lFolder As Long, _
ByVal lReadEntry As Long, _
ByVal sAttachment As String, _
ByVal lLicence As Long) As Long

Parameters

sService
 | A string representing the name of the mail account to lookup from.
lFolder
 | A long representing the folder to retrieve the email from. 1 = Inbox, 0 = Drafts.
lReadEntry
 | A long representing the index of the email to read the attachment name from.
sAttachment
 | A string variable used to store the returned attachment name.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sListMail

Mail Function Reference

sListMail

Mail Function Reference

This function returns the list of email in the specified folder.

Declare Function sListMail Lib "SapphireMail.dll" ( _
ByVal sService As String, _
ByVal lFolder As Long, _
ByRef lEntries As Long, _
ByVal sSubjects As String, _
ByVal sAttachFlags As String, _
ByVal sReadFlags As String, _
ByVal lLicence As Long) As Long

Parameters

sService
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | A long specifying the folder to use. 1 = Inbox, 0 = Drafts.
lEntries
 | A long variable used to return the number of emails returned.
sSubjects
 | A string variable used to return the email subjects. Each subject is seperated by the bar (|) character.
sAttachFlags
 | A string variable used to return whether the emails have attachments, seperated by the bar (|) character.
sReadFlags
 | A string variable used to return whether the emails have been read, seperated by the bar (|) character.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sListServices

Mail Function Reference

sListServices

Mail Function Reference

This function returns the list of mail accounts existing on the device.

Declare Function sListServices Lib "SapphireMail.dll" (ByRef lEntries As Long, _
ByVal sServices As String, _
ByVal lLicence As Long) As Long

Parameters

lEntries
 | A long variable used to store the number of services on the device.
sServices
 | A string variable used to store the list of services seperated by the '|' character.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sReadMail

Mail Function Reference

sReadMail

Mail Function Reference

This function retrieves the email information and body.

Declare Function sReadMail Lib "SapphireMail.dll" ( _
ByVal sService As String, _
ByVal lFolder As Long, _
ByVal lReadEntry As Long, _
ByVal sSenderName As String, _
ByVal sSenderEmail As String, _
ByVal sSubject As String, _
ByRef lAttachment As Long, _
ByVal sBody As String, _
ByVal lLicence As Long) As Long

Parameters

sService
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | A long specifying the folder to use. 1 = Inbox, 0 = Drafts.
lReadEntry
 | A long specifying the index of the email to read.
sSenderName
 | A string used to return the sender's name.
sSenderEmail
 | A string used to return the sender's email address.
sSubject
 | A string used to return the email's subject.
lAttachment
 | A long used to return whether the email has an attachment or not. 1 = Yes, 0 = No.
sBody
 | A string used to return the email's body.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


sSaveAttachment

Mail Function Reference

sSaveAttachment

Mail Function Reference

This function saves an attachment to file.

Declare Function sSaveAttachment Lib "SapphireMail.dll" ( _
ByVal sService As String, _
ByVal lFolder As Long, _
ByVal lReadEntry As Long, _
ByVal sAttachment As String, _
ByVal lLicence As Long) As Long

Parameters

sServer
 | A string specifying the name of the service account to obtain the list of emails from.
lFolder
 | A long specifying the folder to use. 1 = Inbox, 0 = Drafts.
lReadEntry
 | A long specifying the index of the email to read.
sAttachment
 | A string specifying the destination location and filename of the attachment.
lLicence
 | A long specifying the Sapphire Mail licence number.

Return Values

The return value can be ignored for this function.


Sapphire IMEI Utility

Sapphire IMEI Utility Contents

The Sapphire IMEI Utility is designed for reading the International Mobile Equipment Identifier (IMEI) and International Mobile Subscriber Identity (IMSI) from Pocket PC Phone Edition devices. This documentation refers to version 3.0 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire IMEI Utility is designed for reading the device's IMEI and IMSI number of supported phone edition devices.

Version History

v3.0 | Added support for the IMSI number
v2.0 | Support for multiple sim card devices
v1.0 | VB.NET and eVB Compatible Initial release of Sapphire Mail


Supported Hardware

The current supported hardware for the Sapphire IMEI Utility are:

  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Smartphone 2002-ARM
  • Smartphone 2002-X86
  • Smartphone 2003-ARM
  • Smartphone 2003-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire IMEI Utility comes with a demo project that shows how monitor for button presses made by the user on the device. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sIMEI | Retrieves the device's IMEI number.
sIMSI | Retrieves the device's IMSI number.


sIMEI

IMEI Function Reference

sIMEI

IMEI Function Reference

This function retrieves the device's IMEI number.

<DllImport("SapphireIMEI.dll")> _
Public Sub sIMEI(ByVal sIMEI As String, ByVal hInstance As Integer, ByVal lLicence As Integer)
End Sub

Parameters

sIMEI
 | A string variable used to return the 15 digit IMEI number.
hInstance
 | An integer value of the instance to the application form.
lLicence
 | An integer specifying the Sapphire IMEI licence number.

Return Values

None


sIMSI

IMEI Function Reference

sIMSI

IMEI Function Reference

This function retrieves the device's IMSI number.

<DllImport("SapphireIMEI.dll")> _
Public Sub sIMSI(ByVal sIMSI As String, ByVal hInstance As Integer, ByVal lLicence As Integer)
End Sub

Parameters

sIMSI
 | A string variable used to return the IMSI number.
hInstance
 | An integer value of the instance to the application form.
lLicence
 | An integer specifying the Sapphire IMEI licence number.

Return Values

None


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sIMEI | Retrieves the device's IMEI number.
sIMSI | Retrieves the device's IMSI number.


sIMEI

IMEI Function Reference

sIMEI

IMEI Function Reference

This function retrieves the device's IMEI number.

Declare Sub sIMEI Lib "SapphireIMEI.dll" (ByVal sIMEI As String, ByVal hInstance As Long, ByVal lLicence As Long)

Parameters

sIMEI
 | A string variable used to return the 15 digit IMEI number.
hInstance
 | A long value of the instance to the application form.
lLicence
 | A long specifying the Sapphire IMEI licence number.

Return Values

None


sIMSI

IMEI Function Reference

sIMSI

IMEI Function Reference

This function retrieves the device's IMSI number.

Declare Sub sIMSI Lib "SapphireIMEI.dll" (ByVal sIMSI As String, ByVal hInstance As Long, ByVal lLicence As Long)

Parameters

sIMSI
 | A string variable used to return the IMSI number.
hInstance
 | A long value of the instance to the application form.
lLicence
 | A long specifying the Sapphire IMEI licence number.

Return Values

None


Sapphire Battery Utility

Sapphire Battery Utility Contents

The Sapphire Battery Utility is designed for reading the device's battery power level. This document is for version 1.00 of the utility.

  • Release Notes
  • Supported Hardware
  • Demo Project
  • VB.NET Function Reference
  • eVB Function Reference

For licence and purchase information, click here.


Release Notes

Utility Overview

The Sapphire Battery Utility is designed for reading the device's battery power level.

Version History

v1.0 VB.NET and eVB Compatible
Initial release of Sapphire Battery


Supported Hardware

The current supported hardware for the Sapphire Battery Utility are:

  • 602IE-X86
  • Dolphin7400-ARM
  • FW500-SH3
  • HDT600-SH4
  • HPC Pro2.11-ARM
  • HPC Pro2.11-MIPS
  • HPC Pro2.11-SH3
  • HPC Pro2.11-SH4
  • HPC Pro2.11-X86-Emulator
  • HPC2000-ARM
  • HPC2000-MIPS
  • HPC2000-X86
  • Husky FEX21-MIPS
  • IT500-ARM-XScale
  • NetPad-ARM
  • Palm Size PC 2.11-MIPS
  • Palm Size PC 2.11-SH3
  • Palm Size PC 2.11-X86-Emulator
  • Pocket PC 2002-ARM-XScale
  • Pocket PC 2002-X86
  • Pocket PC 2003-ARM-XScale
  • Pocket PC 2003-X86
  • Pocket PC-ARM
  • Pocket PC-MIPS
  • Pocket PC-SH3
  • Pocket PC-X86-Emulator
  • PT930-MIPS
  • PT930SA-ARM
  • Smartphone-ARM
  • Smartphone-X86

We fully recommend that you download the personal use version of the utility with the associated demo project and test the utility on your desired device before purchasing.


Demo Project

The Sapphire Battery Utility comes with a demo project that shows how monitor for button presses made by the user on the device. The demo is downloadable from www.sapphire-solutions.co.uk and contains both the eMbedded Visual Basic 3.0 and Visual Basic .NET project files.


VB.NET Function Reference

There are a variety of functions that are available when using the utility with Visual Basic .NET.

Function Reference

sBatteryPercent Retrieves the battery power level.


sBatteryPercent

Battery Function Reference

sBatteryPercent

Battery Function Reference

This function retrieves the device's battery power level.

<DllImport("SapphireBattery.dll")> _
Public Function sBatteryPercent(ByVal lLicence As Integer) As Integer
End Function

Parameters

lLicence
An integer specifying the Sapphire Battery licence number.

Return Values

Returns an integer value specifying the percentage of the battery power between 0 and 100. If the percentage is 255, the battery is on charge.


eVB Function Reference

There are a variety of functions that are available when using the utility with eMbedded Visual Basic.

Function Reference

sBatteryPercent Retrieves the battery power level.


sBatteryPercent

Battery Function Reference

sBatteryPercent

Battery Function Reference

This function retrieves the device's battery power level.

Declare Function sBatteryPercent Lib "SapphireBattery.dll" (ByVal lLicence As Long) As Long

Parameters

lLicence
A long specifying the Sapphire Battery licence number.

Return Values

Returns a long value specifying the percentage of the battery power between 0 and 100. If the percentage is 255, the battery is on charge.


Frequently Asked Questions
General Questions
  • Why can I not see the DLL files in the downloaded Zip file?
  • Which DLL do I install?
  • How do I install a DLL?
  • Which project file do I run from the demo Zip file?
  • What's the difference between the eVB and VB.NET projects?
  • I get a message saying that the "Active X component can't create object"
  • Do I need a different DLL for Pocket PC 2003 Second Edition?
  • If I upgrade a DLL, what do I need to do?

Utility Specific Questions

Sapphire RAS Utility

  • What's the difference between asynchronous and synchronous connections?

Sapphire FTP Utility

  • Why can I not see any files on the remote server?
  • I get error 12003, what does this mean?
  • I get error 12103, what is happening here?
  • I can't connect to my FTP server
  • The file transfer hangs or fails when using ActiveSync
  • sFTPPut and sFTPGet don't work
  • I am not seeing the error text properly
  • The file I am uploading is zero bytes and it shouldn't be
  • I have problems transferring multiple files through ActiveSync
  • I can only connect to IP address and not server domain names
  • What's the difference between passive and active mode?

Sapphire Encrypt Utility

  • How secure is the encryption algorithm?

Sapphire GZip Utility

  • I receive error 2 when extracting a file from a zip file
  • I receive error 1 when extracting a file from a zip file

Sapphire IrDA Utility

  • Can I print graphics using this utility?
  • I cannot print multiple pages at once
  • I cannot connect to my printer

If your question is still unanswered, then contact support for further assistance.


General Questions

Why can I not see the DLL files in the downloaded Zip file?

You may have your file manager configured so that system files are hidden. Since a DLL file is considered as a system file it may not be visible appearing as though the files do not exist. Go to the folder options and ensure that system and hidden files are visible.

Which DLL do I install?

The DLLs have been organised into their associated directory relating to the device it has been compiled for. Simply select the correct directory that relates to the device you wish to install it onto. For example, if you are using an ARM or XScale processor running Pocket PC 2002, you will want the DLL inside the folder similar to "Pocket PC 2002-ARM-XScale".

How do I install a DLL?

Please refer to the following installation instructions.

Which project do I run from the demo Zip file?

There are two projects included in the demo Zip file, the eVB and the VB.NET projects. The eVB project can be found under \eVB and the project file will have the .ebp extension. The VB.NET project can be found under \VB.NET and the project file will have the .VBDPROJ extension.

What's the difference between the eVB and VB.NET projects?

There are minor changes that exist when calling the DLL from either VB project. One to be careful of is that eVB only supports the Long data types and VB.NET only supports the Integer data type.

I get a message saying that the "Active X component can't create object"

If you eVB project returns with the error "An error was encountered while running this program:Active X component can't create object", the chances are that all the components used by the eVB project are not insalled on your device. It is recommended that you go to project properties and enable the Update Components Frequency to 'Always' and select both update runtime files and update project components. The next time you run your eVB project all the necessary components should be updated on your device. You can disable these after if you are only making minor changes to the code in the future.

Do I need a different DLL for Pocket PC 2003 Second Edition?

No, you can simply use the standard Pocket PC 2003 DLL.

If I upgrade a DLL, what do I need to do?

Updates in later version of the DLL may have different paramter values in the function calls. Please check that your application now uses the updated functions before running the application.


Sapphire RAS Utility Questions

What's the difference between asynchronous and synchronous connections?

Synchronous connections means that your application wont return from the DLL until the device has fully connected or failed. This is simpler to implement into your application. Asynchronous connections uses a timer to monitor the status of the connection procedure. It keeps the control in your application allowing your to give advanced status messages to your user and allow them to cancel the connection sould they require. This is far more complex to implement.

Please refer to the downloadable demo project for examples on how to implement both.


Sapphire FTP Utility Questions

Why can I not see any files on the remote server?

If you have found that you can connect to your remote server but cannot see any files, you may find that you need to change whether you connect in passive or non-passive mode. Alternatively, please ensure that there are files in your remote FTP server's default directory.

I get error 12003, what does this mean?

This may be caused by an unexpected status error being returned by the remote FTP server. The following refers to this error when using non-Microsoft FTP servers:

http://support.microsoft.com/default.aspx?scid=KB;en-us;q168492

Other suggestions would be to verify the security permissions for the FTP account ensuring that it has read and write access to the FTP directory.

Please ensure that you are passing in the Passive option as either 1 for Passive mode and 0 for Active mode. Please do not pass in a boolean variable as this has been known to cause problems.

I get error 12103, what is happening here?

It is most likely that the error number 12103 translates to the system error number of 12003. Please refer to the above.

I can't connect to my FTP server

This may be caused for a variety of reasons. It could be a misspell in the server's domain name or IP address or a problem at some point within the network. One recommendation is to verify the connection to your FTP server by using a PC based FTP client application (e.g. DOS FTP) to connect to your server. If possible, try to ensure that this client application is connecting in a similar manner as your device, for example, through the same ISP or internal network.

If you are using Pocket PC 2002, please ensure that you have the End User Update (EUU2) patch installed on your client device. There was an initial bug in the underlying operating system that caused problems when trying to connect to FTP servers. You should be able to find the update from your manufacturer's web site. Sadly the emulator version also suffers from the same problem.

Please note, if you are using Pocket PC 2002, please ensure that you have the latest patch installed called EUU2 (downloadable from your manufacturers web site). There is a known problem when trying to connect to FTP servers and updating this will fix the problem. Sadly the Emulator version of Pocket PC 2002 also suffers from the same problem. Here are some manufacturer's web site links:

  • End User Update 2 for Casio E-200
  • End User Update 2 for HP Jornada
  • End User Update 2 for HP/Compaq iPaq
  • End User Update 3 for HP/Compaq iPaq
  • End User Update 2 for AudioVox Maestro (re-branded Toshiba e570)
  • End User Update 2 for Toshiba e310

The file transfer hangs or fails when using ActiveSync

This may be a problem caused by ActiveSync itself. In some situations it has been found that ActiveSync times out a connection that can interrupt any client applications such as the Sapphire FTP Utility. The only recommendation would be to try and connect via a different method such as though a LAN adapter.

sFTPPut and sFTPGet don't work

If you are using Pocket PC 2002 then you may find the sFTPPut and sFTPGet functions do not work. Please use the sFTPPush and sFTPPull functions as a replacement.

I am not seeing the error text properly

You may not see your error messages properly if you have not initialised the message string variable with some space in memory. It is recommended that you allocate the message with an associated number of spaces in VB before using it within the Sapphire FTP DLL. Please refer to the demo project on how to do this.

The file I am uploading is zero bytes and it shouldn't be

This is a common problem when using earlier versions of ActiveSync to connect to your FTP server. For some reason, ActiveSync can terminate an upload transfer to some FTP servers resulting in the application unexpectedly completing the transfer, hence it being zero bytes. Please ensure that you are using at least ActiveSync version 3.7.1 to resolve this issue.

I have problems transferring multiple files through ActiveSync

You may find instability issues when transferring multiple file to/from your FTP server through ActiveSync. The only recommended resolution to this is to try an alternative connection method such as GSM or direct LAN access.

I can only connect to IP address and not server domain names

This is most likely due to a configuration problem with your network on the Pocket PC. Your device may not have the correct DNS server addresses configured so it is unable to resolve the DNS name of your FTP server.

What's the difference between passive and active mode?

How do you know when to use active or passive mode. Well, before we go into that, let's explain a little about how FTP works.

When you make an FTP connection to your server you create what is called a control connection. This is most commonly done using port 21. This control connection allows the client to request actions from the server. This could be as simple as logging into the server to creating directories and deleting files.

There are two types of data that you will transfer. The first will be the directory listing and the second will be a file. The control connection will request that a data connection be opened for the actual data. The data connection can either be used to send data (upload a file) or receive data (download a file or directory listing).

It is then common for an FTP connection to have a new connection created to your server for this so called data connection. So, who connects to whom for the data connection? Does the client connect to the server again (just like for the control connection on port 21)? Or does the server connect back to the client?

This is where active and passive mode comes in.

Active Mode

This is where the server connects back to the client. This will only work if the server can see the IP address of the client. If the client’s IP address is routed through an internal network or behind a firewall, then the server will not be able to see it and the data connection will timeout.

Passive Mode

This is where the client creates the connection to the server. This is ideal if your client is behind a firewall. But sometimes the FTP server may be behind a firewall and won’t allow any other connections other than port 21. You would have to contact the administrator of the server to allow some passive connection port numbers to be allowed by the firewall if active mode isn’t an option.


Sapphire Encrypt Utility Questions

How secure is the encryption algorithm?

The Sapphire Encrypt Utility uses the standard Microsoft CryptoAPI functionality. This is symmetric encryption is provided by the RC2 40-bit key algorithm. Using a 40-bit encryption key algorithm gives over one trillion possible decryption keys.


Sapphire GZip Utility Questions

I receive error 2 when extracting a file from a zip file

Error 2 means that the file could not be found. Please verify the filename of the file you are extracting and ensure that it exists in the zip file.

I receive error 1 when extracting a file from a zip file

There was a problem extracting the file. Please ensure that the zip file has not become corrupted.


Sapphire IrDA Utility Questions

Can I print graphics using this utility?

The Sapphire IrDA Utility allows printer specific escape codes to be sent to the printer. Some printers have different functionality than others so it is recommended that you refer to your printer's specification to find out what it supports.

I cannot print multiple pages at once

If you find your printing stops after a page or so, it is most likely due to the printer's buffer oferflowing. Please try the following to resolve this:

1. Reconnect to the printer at specific intervals. This will help clear the printer buffer.
2. Add a delay to your project to allow the printer to 'catch-up' with the application.

I cannot connect to my printer

It is common for the IrDA port to be shared with any bluetooth and barcode scanning devices. Please ensure that these are disabled before printing using the IrDA utility.


Licence and Purchase Information
Licence Information

There are two licence options available for each Sapphire utility:

Personal Use

This licence is designed for developers who are either working on personal projects or simply wish to test the utility before any decision to purchase. You can use this free of charge but will receive a popup message a certain intervals during the utilities use informing that the utility is for personal use only.

Commercial Use

This licence is a popup free version of the utility and allows you or your company to create any number of projects using the utility. The utility is provided royalty free where only a one off payment, regardless of how many projects it is included in. You are not allowed to resell the utility in whole or part, but are allowed to use its functionality within your application. You are allowed to package the licensed utility for the target device with distribution of your application. The application the utility is used for must be developed by the registered licence holder.

Whilst every effort is made to ensure that this product functions correctly, we can not be responsible for any problems that this may cause due to bugs in the utility or incorrect use of the utility. Please ensure that this utility works fully with your target device using the demo version before purchasing the licensed version. Please do report any problems you encounter or enhancements that you may require for future versions.

Purchase Information

To purchase a licence for any of the utilities, please visit www.sapphire-solutions.co.uk. You can purchase any of the utilities online a secure internet connection. Once payment has been made, you will receive a unique licence number and access to download the utility from our server within a few minutes.

If you are considering purchasing more than one utility, we recommend that you look at our combination deals which entitles you to a great saving compared to purchasing them individually.

Each utility comes with a full 12 months email support. If you require extended support then we recommend purchasing the upgrade for your software to get the latest version and an extended 12 months support.


Support
Utility Support

Upon purchasing a licence for any of the Sapphire Utilities, you will receive a full 12 months email support. If you wish to extend your support for a further 12 months you can purchase a support package from www.sapphire-solutions.co.uk. Please read our FAQ section before contacting support with your query.

Support Email Addresses

Utility | Email Address
Sapphire RAS | ras@sapphire-solutions.co.uk
Sapphire FTP | ftp@sapphire-solutions.co.uk
Sapphire IrDA | irda@sapphire-solutions.co.uk
Sapphire GZip | gzip@sapphire-solutions.co.uk
Sapphire Encrypt | encrypt@sapphire-solutions.co.uk
Sapphire Buttons | buttons@sapphire-solutions.co.uk
Sapphire Mail | mail@sapphire-solutions.co.uk
Sapphire IMEI | imei@sapphire-solutions.co.uk
Sapphire Battery | battery@sapphire-solutions.co.uk


Loading...


Sapphire Solutions Ltd - Utility Manuals

Manual Contents

This manual is designed for developers looking to integrate any of the following utilities into a mobile application:

  • Sapphire RAS Utility
  • Sapphire FTP Utility
  • Sapphire IrDA Utility
  • Sapphire GZip Utility
  • Sapphire Encrypt Utility
  • Sapphire Buttons Utility
  • Sapphire IMEI Utility
  • Sapphire Mail Utility
  • Sapphire Battery Utility

Written By

Martin Adams

Last Updated: 13 May, 2004