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