Remote Access Service

Remote Access Service (RAS) lets users at remote locations work as if connected directly to a computer network, accessing one or more RAS servers.

***********************

To set the language of errors text and connection states text,default language is English.
 procedure

 setRas_lan(object lan)

lan

It can be "en" for English  or "pe" for Persian

***********************

To get connection state text

function

get_RASCONNSTATE_text(object STATE)

return : Connection state text.

STATE

value of  connection state

***********************

The RasGetErrorString function obtains an error message string for a specified Remote Access Service (RAS) error value.

function

RasGetErrorString(object uErrorValue)

return : string: error text

uErrorValue

Specifies the error value of interest. These are values returned by one of the RAS functions

***********************

The RasCreatePhonebookEntry function creates a new phonebook entry. The function displays a dialog box in which the user types information about the phonebook entry.

procedure

RasCreatePhonebookEntry(object hwnd,object fn)

hwnd:

 handle to the parent window of the dialog box

fn:

string that specifies the full path and filename of the phonebook file. 
Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

************************

The RasHangUp function terminates a remote access connection. The connection is specified with a Remote Access Service (RAS) connection handle. The function releases all RASAPI32.DLL resources associated with the handle.

function

RasHangUp(object hrasconn)

Return :

If the function succeeds, the return value is zero.
If the function fails, the return value is a nonzero error value listed in the RAS header file, or ERROR_INVALID_HANDLE.you can use RasGetErrorString to get error text.

hrasconn

Identifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.

*************************

The RasDialFunc function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a Remote Access Service (RAS) connection process.you should define   callback function like this and set instead of RasDialFunc your name

function

RasDialFunc(int unMsg,int  rasconnstate,int dwError )


unMsg

Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.

rasconnstate

Specifies a  value that indicates the state the RasDial remote access connection process is about to enter.

you can use get_RASCONNSTATE_text to get connection state text

dwError

Indicates the error that has occurred, or zero if no error has occurred.
RasDial calls RasDialFunc with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDialFunc is called again with a nonzero dwError value.

*************************

A RasDialFunc1 function is an application-defined or library-defined callback function that the RasDial function calls when a change of state occurs during a remote access connection process. A RasDialFunc1 function is comparable to a RasDialFunc function, but is enhanced by the addition of two parameters: a handle to the Remote Access Server (RAS) connection, and an extended error code.you should define  callback function like this and set instead of RasDialFunc1 your name.

function

 RasDialFunc1(int hrasconn,int unMsg,int rascs,int dwError ,int dwExtendedError)


hrasconn

Provides a handle to the RAS connection, as returned by RasDial.

unMsg

Specifies the type of event that has occurred. Currently, the only event defined is WM_RASDIALEVENT.

rascs

Specifies a  value that indicates the state the RasDial remote access connection process is about to enter.

you can use get_RASCONNSTATE_text to get connection state text
 

dwError

Specifies the error that has occurred. If no error has occurred, dwError is zero.
RasDial calls RasDialFunc1 with dwError set to zero upon entry to each connection state. If an error occurs within a state, RasDial calls RasDialFunc1 again with a nonzero dwError value.
In some error cases, the dwExtendedError parameter contains extended error information.

dwExtendedError

Specifies extended error information for certain nonzero values of dwError. For all other values of dwError, dwExtendedError is zero.
The contents of dwExtendedError are defined for values of dwError as follows:

dwError                                                                   dwExtendedError
ERROR_SERVER_NOT_RESPONDING             Specifies the NetBIOS error that occurred.
ERROR_NETBIOS_ERROR                                  Specifies the NetBIOS error that occurred.
ERROR_AUTH_INTERNAL                                  Specifies an internal diagnostics code.
ERROR_CANNOT_GET_LANA                           Specifies a routing error code, which is a RAS error.
 

*************************

The RasDial function establishes a Remote Access Service (RAS) connection between a RAS client and a RAS server. The connection data includes callback and user authentication information.

function

 RasDial(object lpRasDialExtensions
,object lpszPhonebook
,object lpRasDialParams
,object dwNotifierType
,object lpvNotifier)
 

lpRasDialExtensions

NULL

 lpszPhonebook

string that specifies the full path and filename of the phonebook file. This parameter can be NULL, and typically is; in that case, RasDial
uses the default phonebook file RASPHONE.PBK.


lpRasDialParams

={szEntryName,szPhoneNumber,szCallbackNumber,szUserName,szPassword,szDomain}
 

szEntryName

Specifies a string containing the phonebook entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port, in which case a non-empty szPhoneNumber must be provided.

szPhoneNumber

Specifies a string containing an overriding phone number. An empty string ("") indicates that the phonebook entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".

szCallbackNumber

Specifies a string containing a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phonebook should be used for callback.

szUserName

Specifies a string containing the user's user name. This string is used to authenticate the user's access to the remote access server.

szPassword

Specifies a string containing the user's password. This string is used to authenticate the user's access to the remote access server.

szDomain

Specifies a string containing the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phonebook for the entry.

dwNotifierType

Specifies the nature of the lpvNotifier parameter. If lpvNotifier is NULL, dwNotifierType is ignored. If lpvNotifier is not NULL, set dwNotifierType to one of the following values:

Value                                   Meaning
#FFFFFFFF            The lpvNotifier parameter is a handle to a window to receive progress notification messages. In a progress   notification message, wParam is   the equivalent of the rasconnstate parameter of RasDialFunc and RasDialFunc1, and lParam is the equivalent of the dwError parameter of RasDialFunc and RasDialFunc1. The progress notification message uses a system registered message code. You can obtain the value of this message code as follows:

0                                The lpvNotifier parameter points to a RasDialFunc callback function.
 

1                                The lpvNotifier parameter points to a RasDialFunc1 callback function.

lpvNotifier

Specifies a window handle or a RasDialFunc or RasDialFunc1 callback function to receive RasDial event notifications. The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.
If this parameter is not NULL, RasDial sends the window a message, or calls the callback function, for each RasDial event. Additionally, the RasDial call operates asynchronously: RasDial returns immediately, before the connection is established, and communicates its progress via the window or callback function.

If lpvNotifier is NULL, the RasDial call operates synchronously: RasDial does not return until the connection attempt has completed successfully or failed.
If lpvNotifier is not NULL, notifications to the window or callback function can occur at any time after the initial call to RasDial. Notifications end when one of the following events occurs:

· The connection is established. In other words, the RAS connection state is RASCS_Connected.
· The connection fails. In other words, dwError is nonzero.
· RasHangUp is called on the connection.

The callback notifications are made in the context of a thread captured during the initial call to RasDial.

*************************

The RasEditPhonebookEntry function edits an existing phonebook entry. The function displays a dialog box in which the user can modify the existing information.

procedure

RasEditPhonebookEntry(object hwnd,object lpszPhonebook,object lpszEntryName)

hwnd

Handle to the parent window of the dialog box.

lpszPhonebook

A string that specifies the full path and filename of the phonebook file. .
Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

lpszEntryName

A string that specifies the name of an existing entry in the phonebook file.

*************************

The RasEnumConnections function lists all active Remote Access Service (RAS) connections. It returns each connection's handle and phonebook entry name.

 function

RasEnumConnections()

return :If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

If successful return is sequence:an array of all active Remote Access Service (RAS) connections

and also every subsequence is a sequence as follow:

{hrasconn,szEntryName,szDeviceType,szDeviceName}

hrasconn

Specifies the remote access connection. This handle is used in other remote access API calls.

szEntryName

A string that specifies the phonebook entry used to establish the remote access connection. If the connection was established using an empty entry name, this string consists of a "." followed by the connection phone number.

szDeviceType

A string that contains the device type through which the connection is made.
Windows NT: This member is defined only if you build with the WINVER constant defined as #400 or greater. By default, the SDK for Windows NT 3.51 defines WINVER as less than #400.

szDeviceName

A string that contains the device name through which the connection is made.
Windows NT: This member is defined only if you build with the WINVER constant defined as #400 or greater.

*****************************

The RasEnumEntries function lists all entry names in a remote access phonebook.

function

 RasEnumEntries(object reserved,object lpszPhonebook)

return:If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

And if successful return is a sequence: remote access phonebook entry names.

reserved

Reserved; must be NULL.

lpszPhonebook

Windows NT

A string that specifies the full path and filename of the phonebook file. This parameter can be NULL, and typically is; in that case, RasEnumEntries uses the default phonebook file RASPHONE.PBK.

Windows 95

This parameter is ignored. Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

************************

The RasGetConnectStatus function retrieves information on the current status of the specified remote access connection. An application can use this call to determine when an asynchronous RasDial call has completed.

function

RasGetConnectStatus(object hrasconn)

return :If the function fails, the return value is a nonzero error value listed in the RAS header file or one of ERROR_BUFFER_TOO_SMALL or ERROR_NOT_ENOUGH_MEMORY.

And if successful return is a sequence :{rasconnstate,Error,DeviceType,DeviceName}

rasconnstate

Specifies a value that indicates the current state of the RasDial connection process; that is, the piece of the RasDial process that is currently executing.
Two state values are especially significant:

State Meaning
RASCS_Connected          Indicates that the connection has completed successfully.
RASCS_Disconnected       Indicates that the connection has failed.
 

Error

If nonzero, indicates the reason for failure. The value is one of the error values from the RAS header file or one of ERROR_NOT_ENOUGH_MEMORY or ERROR_INVALID_HANDLE.

DeviceType

A string that specifies the type of the current device, if available. For example, common device types supported by RAS remote access service are "modem", "pad", "switch", "isdn", or "null".

DeviceName

A string that specifies the name of the current device, if available. This would be the name of the modem ¾ for example, "Hayes Smartmodem 2400"; the name of the PAD, for example "US Sprint"; or the name of a switch device, for example "Racal-Guardata".

hrasconn

Identifies the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial or RasEnumConnections.

************************

The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phonebook entry.

function

RasGetEntryDialParams(object pszPhonebook,object szEntryName )

return:

If the function fails, the return value can be one of the following error codes:

Value Description
ERROR_BUFFER_INVALID
The lprasdialparams or lpfPassword pointer is invalid, or the lprasdialparams buffer is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK
The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
The phonebook entry does not exist

If successful return is a sequence :{fPassword,{szEntryName,szPhoneNumber,szCallbackNumber,szUserName,szPassword
,szDomain}}

fPassword

 Indicates whether the function retrieved the password associated with the user name for the phonebook entry. The function sets this flag to TRUE if the user's password was returned in the szPassword .

szEntryName

Specifies a string containing the phonebook entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port.

szPhoneNumber

Specifies a string containing an overriding phone number. An empty string ("") indicates that the phonebook entry's phone number should be used. If szEntryName is "", szPhoneNumber cannot be "".

szCallbackNumber

Specifies a string containing a callback phone number. An empty string ("") indicates that callback should not be used. This string is ignored unless the user has "Set By Caller" callback permission on the RAS server. An asterisk indicates that the number stored in the phonebook should be used for callback.

szUserName

Specifies a string containing the user's user name. This string is used to authenticate the user's access to the remote access server.

szPassword

Specifies a string containing the user's password. This string is used to authenticate the user's access to the remote access server.

szDomain

Specifies a string containing the domain on which authentication is to occur. An empty string ("") specifies the domain in which the remote access server is a member. An asterisk specifies the domain stored in the phonebook for the entry

pszPhonebook

A string that specifies the full path and filename of the phonebook file.
Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

szEntryName

Specifies a string containing the phonebook entry to use to establish the connection. An empty string ("") specifies a simple modem connection on the first available modem port.

*************************

The RasGetProjectionInfo function obtains information about a remote access projection operation for a specified remote access component protocol.

 function

RasGetProjectionInfo(object hrasconn,
object rasprojection)

return :If the function fails, the return value is an error code and if successful return is a sequence ,the sequence for every rasprojection value is different. You can see the description of rasprojection values.

hrasconn

Handle to the remote access connection of interest. An application obtains a Remote Access Service (RAS) connection handle from the RasDial or RasEnumConnections function.

rasprojection

 Value that specifies the protocol of interest.

RASP_Amb

Specifies the Authentication Message Block (AMB) authentication protocol. AMB is a NetBIOS-based protocol used to authenticate with downlevel remote access servers ( all those prior to Windows NT 3.5).

return is :{Error,NetBiosError,bLana}

Error

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

NetBiosError

If Error has the value ERROR_NAME_EXISTS_ON_NET, the NetBiosError field contains a zero-terminated string that is the NetBIOS name that caused the conflict. For other values of Error, this field contains the null string.

bLana

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value #FF if a connection was not established.
 

RASP_PppNbf

Specifies the NetBEUI Framer (NBF) protocol. NBFCP is a PPP network control protocol used to negotiate the parameters necessary to ship NetBEUI packets on a WAN link.

return is:{Error,dwNetBiosError,szNetBiosError,szWorkStationName}

Error

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

dwNetBiosError

If Error has the value ERROR_SERVER_NOT_RESPONDING or ERROR_NETBIOS_ERROR, the dwNetBiosError field contains the NetBIOS error that occurred. For other values of Error, this field contains zero.

szNetBiosError

If Error has the value ERROR_NAME_EXISTS_ON_NET, the szNetBiosError field contains a string that is the NetBIOS name that caused the conflict. For other values of Error, this field contains the null string.

szWorkStationName

Contains a  string that is the local workstation's computer name. This unique computer name is the closest NetBIOS equivalent to a client's NetBEUI address on a remote access connection.

bLana

Identifies the NetBIOS network adapter identifier, or LANA, on which the remote access connection was established. This member contains the value #FF if a connection was not established.
 

RASP_PppIpx

Specifies the Internetwork Packet Exchange (IPX) control protocol. IPXCP is a PPP network control protocol used to negotiate the parameters necessary to ship IPX packets on a WAN link.

return is:{Error,szIpxAddress}

Error

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

szIpxAddress

Contains a  string that is the client's IPX address on the RAS connection. This address string has the form net.node; for example, "1234ABCD.12AB34CD56EF".


 

RASP_PppIp

Specifies the Internet Protocol (IP) control protocol. IPCP is a PPP network control protocol used to negotiate the parameters necessary to ship IP packets on a WAN link.

return is:{Error,szIpAddress,szServerIpAddress}

Error

Contains the result of the PPP control protocol negotiation. A value of zero indicates success. A nonzero value indicates failure, and is the actual fatal error that occurred during the control protocol negotiation, the error that prevented the projection from completing successfully.

szIpAddress

Contains a  string that is the client's IP address on the RAS connection. This address string has the form a.b.c.d; for example, "11.101.237.71".

szServerIpAddress

Contains a string that is the IP address of the remote PPP peer (that is, the server's IP address). This string is in "a.b.c.d" form. PPP does not require that servers provide this address, but Windows NT servers will consistently return the address anyway. Other PPP vendors may not provide the address. If the address is not available, this member returns an empty string, "".

***********************

The RasSetEntryDialParams function changes the connection information saved by the last successful call to the RasDial or RasSetEntryDialParams function for a specified phonebook entry.

function

RasSetEntryDialParams(object lpszPhonebook,object lprasdialparams,object fRemovePassword)

Return :

If the function succeeds, the return value is zero.
If the function fails, the return value can be one of the following error codes:

Value                                            Description
ERROR_BUFFER_INVALID
                                                    The address or buffer specified by lprasdialparams is invalid.
ERROR_CANNOT_OPEN_PHONEBOOK
                                                    The phonebook is corrupted or missing components.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
                                                     The phonebook entry does not exist.

lpszPhonebook

A string that specifies the full path and filename of the phonebook file.
Windows 95: Dial-up networking stores phonebook entries in the registry rather than in a phonebook file.

lprasdialparams

A sequence : lprasdialparams={szEntryName,szPhoneNumber,szCallbackNumber,szUserName,szPassword,szDomain}

szEntryName

 A string that identifies the phonebook entry to set parameters for.
 

szPhoneNumber

Not used. Set to NULL.
 

szCallbackNumber

A string containing the callback phone number. If szCallbackNumber is an empty string ( "" ), the callback number is not changed.
 

szUserName

A string containing the logon name of the user associated with this entry. If szUserName is an empty string, the user name is not changed.
 

szPassword

A  string containing the password for the user specified by szUserName. If szUserName is an empty string, the password is not changed. If szPassword is an empty string and fRemovePassword is FALSE, the password is set to the empty string. If fRemovePassword is TRUE, the password stored in this phonebook entry for the user specified by szUserName is removed regardless of the contents of the szPassword string.
 

szDomain

A  string containing the name of the domain to log on to. If szDomain is an empty string, the domain name is not changed.
 

fRemovePassword

Indicates whether to remove the phonebook entry's stored password for the user specified by lprasdialparams->szUserName. If fRemovePassword is TRUE, the password is removed.