/* Copyright (c) 2011 Timothy Wall, All Rights Reserved
 *
 * The contents of this file is dual-licensed under 2
 * alternative Open Source/Free licenses: LGPL 2.1 or later and
 * Apache License 2.0. (starting with JNA version 4.0.0).
 *
 * You can freely decide which license you want to apply to
 * the project.
 *
 * You may obtain a copy of the LGPL License at:
 *
 * http://www.gnu.org/licenses/licenses.html
 *
 * A copy is also included in the downloadable source code package
 * containing JNA, in file "LGPL2.1".
 *
 * You may obtain a copy of the Apache License at:
 *
 * http://www.apache.org/licenses/
 *
 * A copy is also included in the downloadable source code package
 * containing JNA, in file "AL2.0".
 */
package com.sun.jna.platform.win32;

import com.sun.jna.Native;
import com.sun.jna.Pointer;
import com.sun.jna.platform.win32.WinDef.BOOLByReference;
import com.sun.jna.platform.win32.WinNT.HANDLE;
import com.sun.jna.platform.win32.WinNT.HANDLEByReference;
import com.sun.jna.platform.win32.WinRas.RASCONN;
import com.sun.jna.platform.win32.WinRas.RASCONNSTATUS;
import com.sun.jna.platform.win32.WinRas.RASCREDENTIALS;
import com.sun.jna.platform.win32.WinRas.RASDIALEXTENSIONS;
import com.sun.jna.platform.win32.WinRas.RASDIALPARAMS;
import com.sun.jna.platform.win32.WinRas.RASENTRY;
import com.sun.jna.platform.win32.WinRas.RAS_STATS;
import com.sun.jna.platform.win32.WinRas.RasDialFunc2;
import com.sun.jna.ptr.IntByReference;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

/**
 * Rasapi32.dll Interface.
 */
public interface Rasapi32 extends StdCallLibrary {
    Rasapi32 INSTANCE = Native.load("Rasapi32", Rasapi32.class, W32APIOptions.DEFAULT_OPTIONS);

    /**
     * The RasDial function establishes a RAS connection between a RAS client and a RAS server.
     * The connection data includes callback and user-authentication information.
     *
     * @param lpRasDialExtensions
     *            Pointer to a RASDIALEXTENSIONS structure that specifies a set of RasDial extended features to enable.
     *            Set this parameter to NULL if there is not a need to enable these features.
     * @param lpszPhonebook
     *            Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file.
     *            If this parameter is NULL, the function uses the current default phone-book file.
     *            The default phone-book file is the one selected by the user in the User Preferences property sheet of the
     *            Dial-Up Networking dialog box.
     * @param lpRasDialParams
     *            Pointer to a RASDIALPARAMS structure that specifies calling parameters for the RAS connection.
     *            Use the RasGetEntryDialParams function to retrieve a copy of this structure for a particular phone-book entry.
     * @param 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.
     * @param lpvNotifier
     *            Specifies a window handle or a RasDialFunc, RasDialFunc1, or RasDialFunc2 callback function to receive
     *            RasDial event notifications.
     *            The dwNotifierType parameter specifies the nature of lpvNotifier. Please refer to its description preceding for further detail.
     * @param lphRasConn
     *            Pointer to a variable of type HRASCONN. Set the HRASCONN variable to NULL before calling RasDial.
     *            If RasDial succeeds, it stores a handle to the RAS connection into *lphRasConn.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasDial(RASDIALEXTENSIONS.ByReference lpRasDialExtensions, String lpszPhonebook, RASDIALPARAMS.ByReference lpRasDialParams, int dwNotifierType, RasDialFunc2 lpvNotifier, HANDLEByReference lphRasConn);

    /**
     * The RasEnumConnections function lists all active RAS connections. It returns each connection's handle and phone-book entry name.
     *
     * @param lprasconn
     *            Pointer to a buffer that receives, on output, an array of RASCONN structures, one for each RAS connection.
     *            On input, an application must set the dwSize member of the first RASCONN structure in the buffer to sizeof(RASCONN)
     *            in order to identify the version of the structure being passed.
     * @param lpcb
     *            Pointer to a variable that, on input, contains the size, in bytes, of the buffer specified by lprasconn.
     *            On output, the function sets this variable to the number of bytes required to enumerate the RAS connections.
     * @param lpcConnections
     *            Pointer to a variable that receives the number of RASCONN structures written to the buffer specified by lprasconn.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasEnumConnections(RASCONN[] lprasconn, IntByReference lpcb, IntByReference lpcConnections);

    /**
     * The RasGetConnectionStatistics function retrieves accumulated connection statistics for the specified connection.
     *
     * @param hrasconn
     *            Handle to the connection. Use RasDial or RasEnumConnections to obtain this handle.
     * @param lpStatistics
     *            Pointer to the RASCONNSTATUS structure that, on output, receives the status information.
     *            On input, set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetConnectionStatistics(HANDLE hrasconn, RAS_STATS.ByReference lpStatistics);

    /**
     * The RasGetConnectionStatistics function retrieves accumulated connection statistics for the specified connection.
     *
     * @param hrasconn
     *            Specifies the remote access connection for which to retrieve the status. This handle must have been obtained from RasDial
     *            or RasEnumConnections.
     * @param lprasconnstatus
     *            Pointer to the RASCONNSTATUS structure that, on output, receives the status information.
     *            On input, set the dwSize member of the structure to sizeof(RASCONNSTATUS) in order to identify the version of the structure being passed.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetConnectStatus(HANDLE hrasconn, RASCONNSTATUS.ByReference lprasconnstatus);

    /**
     * The RasGetCredentials function retrieves the user credentials associated with a specified RAS phone-book entry.
     *
     * @param lpszPhonebook
     *            Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file.
     *            If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the
     *            one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
     * @param lpszEntry
     *            Pointer to a null-terminated string that specifies the name of a phone-book entry.
     * @param lpCredentials
     *            Pointer to the RASCREDENTIALS structure that, on output, receives the user credentials associated with the specified
     *            phone-book entry.
     *            On input, set the dwSize member of the structure to sizeof(RASCREDENTIALS), and set the dwMask member to indicate the
     *            credential information to retrieve. When the function returns, dwMask indicates the members that were successfully retrieved.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetCredentials(String lpszPhonebook, String lpszEntry, RASCREDENTIALS.ByReference lpCredentials);

    /**
     * The RasGetEntryProperties function retrieves the properties of a phone-book entry.
     *
     * @param lpszPhonebook
     *            Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file.
     *            If this parameter is NULL, the function uses the current default phone-book file.
     *            The default phone-book file is the one selected by the user in the User Preferences property sheet of the
     *            Dial-Up Networking dialog box.
     * @param lpszEntry
     *            Pointer to a null-terminated string that specifies an existing entry name.
     *            If an empty string is specified, the function returns default values in the buffers pointed to by the
     *            lpRasEntry and lpbDeviceInfo parameters.
     * @param lpRasEntry
     *            Pointer to a RASENTRY structure followed by additional bytes for the alternate phone number list, if there is one.
     * @param lpdwEntryInfoSize
     *            Pointer to a variable that, on input, specifies the size, in bytes, of the lpRasEntry buffer.
     * @param lpbDeviceInfo
     *            This parameter is no longer used. The calling function should set this parameter to NULL.
     * @param lpdwDeviceInfoSize
     *            This parameter is unused. The calling function should set this parameter to NULL.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetEntryProperties(String lpszPhonebook, String lpszEntry, RASENTRY.ByReference lpRasEntry, IntByReference lpdwEntryInfoSize, Pointer lpbDeviceInfo, Pointer lpdwDeviceInfoSize);

    /**
     * The RasGetProjectionInfo function obtains information about a remote access projection operation for a specified remote access
     * component protocol.
     *
     * @param hrasconn
     *            Handle to the remote access connection of interest. An application obtains a RAS connection handle from the RasDial
     *            or RasEnumConnections function.
     * @param rasprojection
     *            Specifies the RASPROJECTION enumerated type value that identifies the protocol of interest.
     * @param lpprojection
     *            Pointer to a buffer that receives the information specified by the rasprojection parameter. The information is in a
     *            structure appropriate to the rasprojection value.
     * @param lpcb
     *            Pointer to a variable that, on input, specifies the size, in bytes, of the buffer pointed to by lpprojection.
     *            On output, this variable receives the size, in bytes, of the lpprojection buffer.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetProjectionInfo(HANDLE hrasconn, int rasprojection, Pointer lpprojection, IntByReference lpcb);

    /**
     * The RasHangUp function terminates a remote access connection. The connection is specified with a RAS connection handle.
     * The function releases all RASAPI32.DLL resources associated with the handle.
     *
     * @param hrasconn
     *            Specifies the remote access connection to terminate. This is a handle returned from a previous call to RasDial or RasEnumConnections.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasHangUp(HANDLE hrasconn);

    /**
     * The RasSetEntryProperties function changes the connection information for an entry in the phone book or creates a new phone-book entry.
     *
     * @param lpszPhonebook
     *            Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file.
     *            If this parameter is NULL, the function uses the current default phone-book file.
     *            The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up
     *            Networking dialog box.
     * @param lpszEntry
     *            Pointer to a null-terminated string that specifies an entry name.
     * @param lpRasEntry
     *            Pointer to the RASENTRY structure that specifies the new connection data to be associated with the
     *            phone-book entry indicated by the lpszEntry parameter.
     * @param dwEntryInfoSize
     *            Specifies the size, in bytes, of the buffer identified by the lpRasEntry parameter.
     * @param lpbDeviceInfo
     *            Pointer to a buffer that specifies device-specific configuration information.
     *            This is opaque TAPI device configuration information. For more information about TAPI device configuration,
     *            see the lineGetDevConfig function in Telephony Application Programming Interfaces (TAPI) in the Platform SDK.
     * @param dwDeviceInfoSize
     *            Specifies the size, in bytes, of the lpbDeviceInfo buffer.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasSetEntryProperties(String lpszPhonebook, String lpszEntry, RASENTRY.ByReference lpRasEntry, int dwEntryInfoSize, byte[] lpbDeviceInfo, int dwDeviceInfoSize);

    /**
     * The RasGetEntryDialParams function retrieves the connection information saved by the last successful call to the RasDial or
     * RasSetEntryDialParams function for a specified phone-book entry.
     *
     * @param lpszPhonebook
     *           Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file.
     *           If this parameter is NULL, the function uses the current default phone-book file.
     *           The default phone-book file is the one selected by the user in the User Preferences property sheet of the
     *           Dial-Up Networking dialog box.
     * @param lprasdialparams
     *            Pointer to a RASDIALPARAMS structure.
     * @param lpfPassword
     *            Pointer to a flag that indicates whether the function retrieved the password associated with the user
     *            name for the phone-book entry. The lpfPassword parameter is TRUE if the system has saved a password for
     *            the specified entry. If the system has no password saved for this entry, lpfPassword is FALSE.
     * @return If the function succeeds, the return value is ERROR_SUCCESS.
     */
    int RasGetEntryDialParams(String lpszPhonebook, RASDIALPARAMS.ByReference lprasdialparams, BOOLByReference lpfPassword);

    /**
     * The RasGetErrorString function obtains an error message string for a specified RAS error value.
     *
     * @param uErrorValue
     *           Specifies the error value of interest. These are values returned by one of the RAS functions:
     *           those listed in the RasError.h header file.
     * @param lpszErrorString
     *            Pointer to a buffer that receives the error string. This parameter must not be NULL.
     * @param cBufSize
     *            Specifies the size, in characters, of the buffer pointed to by lpszErrorString.
         * @return status
     */
    int RasGetErrorString(int uErrorValue, char[] lpszErrorString, int cBufSize);
}
