dll/win32/netapi32/netbios.h

   1 /* Copyright (c) 2003 Juan Lang
   2  *
   3  * This library is free software; you can redistribute it and/or
   4  * modify it under the terms of the GNU Lesser General Public
   5  * License as published by the Free Software Foundation; either
   6  * version 2.1 of the License, or (at your option) any later version.
   7  *
   8  * This library is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11  * Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public
  14  * License along with this library; if not, write to the Free Software
  15  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  16  */
  17 #ifndef __WINE_NETBIOS_H__
  18 #define __WINE_NETBIOS_H__
  19
  20 /* This file describes the interface WINE's NetBIOS implementation uses to
  21  * interact with a transport implementation (where a transport might be
  22  * NetBIOS-over-TCP/IP (aka NetBT, NBT), NetBIOS-over-IPX, etc.)
  23  */
  24
  25 /**
  26  * Public functions
  27  */
  28
  29 void NetBIOSInit(void) DECLSPEC_HIDDEN;
  30 void NetBIOSShutdown(void) DECLSPEC_HIDDEN;
  31
  32 struct _NetBIOSTransport;
  33
  34 /* A transport should register itself during its init function (see below) with
  35  * a unique id (the transport_id of ACTION_HEADER, for example) and an
  36  * implementation.  Returns TRUE on success, and FALSE on failure.
  37  */
  38 BOOL NetBIOSRegisterTransport(ULONG id, struct _NetBIOSTransport *transport) DECLSPEC_HIDDEN;
  39
  40 /* Registers an adapter with the given transport and ifIndex with NetBIOS.
  41  * ifIndex is an interface index usable by the IpHlpApi.  ifIndex is not
  42  * required to be unique, but is required so that NetWkstaTransportEnum can use
  43  * GetIfEntry to get the name and hardware address of the adapter.
  44  * Returns TRUE on success, FALSE on failure.
  45  * FIXME: need functions for retrieving the name and hardware index, rather
  46  * than assuming a correlation with IpHlpApi.
  47  */
  48 BOOL NetBIOSRegisterAdapter(ULONG transport, DWORD ifIndex, void *adapter) DECLSPEC_HIDDEN;
  49
  50 /* During enumeration, all adapters from your transport are disabled
  51  * internally.  If an adapter is still valid, re-enable it with this function.
  52  * Adapters you don't enable will have their transport's NetBIOSCleanupAdapter
  53  * function (see below) called on them, and will be removed from the table.
  54  * (This is to deal with lack of plug-and-play--sorry.)
  55  */
  56 void NetBIOSEnableAdapter(UCHAR lana) DECLSPEC_HIDDEN;
  57
  58 /* Gets a quick count of the number of NetBIOS adapters.  Not guaranteed not
  59  * to change from one call to the next, depending on what's been enumerated
  60  * lately.  See also NetBIOSEnumAdapters.
  61  */
  62 UCHAR NetBIOSNumAdapters(void) DECLSPEC_HIDDEN;
  63
  64 typedef struct _NetBIOSAdapterImpl {
  65     UCHAR lana;
  66     DWORD ifIndex;
  67     void *data;
  68 } NetBIOSAdapterImpl;
  69
  70 typedef BOOL (*NetBIOSEnumAdaptersCallback)(UCHAR totalLANAs, UCHAR lanaIndex,
  71  ULONG transport, const NetBIOSAdapterImpl *data, void *closure);
  72
  73 /* Enumerates all NetBIOS adapters for the transport transport, or for all
  74  * transports if transport is ALL_TRANSPORTS.  Your callback will be called
  75  * once for every enumerated adapter, with a count of how many adapters have
  76  * been enumerated, a 0-based index relative to that count, the adapter's
  77  * transport, and its ifIndex.
  78  * Your callback should return FALSE if it no longer wishes to be called.
  79  */
  80 void NetBIOSEnumAdapters(ULONG transport, NetBIOSEnumAdaptersCallback cb,
  81  void *closure) DECLSPEC_HIDDEN;
  82
  83 /* Hangs up the session identified in the NCB; the NCB need not be a NCBHANGUP.
  84  * Will result in the transport's hangup function being called, so release any
  85  * locks you own before calling to avoid deadlock.
  86  * This function is intended for use by a transport, if the session is closed
  87  * by some error in the transport layer.
  88  */
  89 void NetBIOSHangupSession(const NCB *ncb) DECLSPEC_HIDDEN;
  90
  91 /**
  92  * Functions a transport implementation must implement
  93  */
  94
  95 /* This function is called to ask a transport implementation to enumerate any
  96  * LANAs into the NetBIOS adapter table by:
  97  * - calling NetBIOSRegisterAdapter for any new adapters
  98  * - calling NetBIOSEnableAdapter for any existing adapters
  99  * NetBIOSEnumAdapters (see) may be of use to determine which adapters already
 100  * exist.
 101  * A transport can assume no other thread is modifying the NetBIOS adapter
 102  * table during the lifetime of its NetBIOSEnum function (and, therefore, that
 103  * this function won't be called reentrantly).
 104  */
 105 typedef UCHAR (*NetBIOSEnum)(void);
 106
 107 /* A cleanup function for a transport.  This is the last function called on a
 108  * transport.
 109  */
 110 typedef void (*NetBIOSCleanup)(void);
 111
 112 /* Adapter functions */
 113
 114 /* Functions with direct mappings to the Netbios interface.  These functions
 115  * are expected to be synchronous, although the first four bytes of the
 116  * reserved member of the ncb are a cancel flag.  A long-running function
 117  * should check whether this is not FALSE from time to time (see the
 118  * NCB_CANCELLED macro), and return NRC_CMDCAN if it's been cancelled.  (The
 119  * remainder of the NCB's reserved field is, well, reserved.)
 120  */
 121
 122 /* Used to see whether the pointer to an NCB has been cancelled.  The NetBIOS
 123  * interface designates certain functions as non-cancellable functions, but I
 124  * use this flag for all NCBs.  Support it if you can.
 125  * FIXME: this isn't enough, need to support an EVENT or some such, because
 126  * some calls (recv) will block indefinitely, so a reset, shutdown, etc. will
 127  * never occur.
 128  */
 129 #define NCB_CANCELLED(pncb) *(const BOOL *)((pncb)->ncb_reserve)
 130
 131 typedef UCHAR (*NetBIOSAstat)(void *adapter, PNCB ncb);
 132 typedef UCHAR (*NetBIOSFindName)(void *adapter, PNCB ncb);
 133
 134 /* Functions to support the session service */
 135
 136 /* Implement to support the NCBCALL command.  If you need data stored for the
 137  * session, return it in *session.  You can clean it up in your NetBIOSHangup
 138  * function (see).
 139  */
 140 typedef UCHAR (*NetBIOSCall)(void *adapter, PNCB ncb, void **session);
 141 typedef UCHAR (*NetBIOSSend)(void *adapter, void *session, PNCB ncb);
 142 typedef UCHAR (*NetBIOSRecv)(void *adapter, void *session, PNCB ncb);
 143 typedef UCHAR (*NetBIOSHangup)(void *adapter, void *session);
 144
 145 /* The last function called on an adapter; it is not called reentrantly, and
 146  * no new calls will be made on the adapter once this has been entered.  Clean
 147  * up any resources allocated for the adapter here.
 148  */
 149 typedef void (*NetBIOSCleanupAdapter)(void *adapter);
 150
 151 typedef struct _NetBIOSTransport
 152 {
 153     NetBIOSEnum           enumerate;
 154     NetBIOSAstat          astat;
 155     NetBIOSFindName       findName;
 156     NetBIOSCall           call;
 157     NetBIOSSend           send;
 158     NetBIOSRecv           recv;
 159     NetBIOSHangup         hangup;
 160     NetBIOSCleanupAdapter cleanupAdapter;
 161     NetBIOSCleanup        cleanup;
 162 } NetBIOSTransport;
 163
 164 /* Transport-specific functions.  When adding a transport, add a call to its
 165  * init function in netapi32's DllMain.  The transport can do any global
 166  * initialization it needs here.  It should call NetBIOSRegisterTransport to
 167  * register itself with NetBIOS.
 168  */
 169
 170 /* NetBIOS-over-TCP/IP (NetBT) functions */
 171
 172 /* Not defined by MS, so make my own private define: */
 173 #define TRANSPORT_NBT "MNBT"
 174
 175 void NetBTInit(void) DECLSPEC_HIDDEN;
 176
 177 #endif /* ndef __WINE_NETBIOS_H__ */