netbios.h 7.08 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
/* Copyright (c) 2003 Juan Lang
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
#ifndef __WINE_NETBIOS_H__
#define __WINE_NETBIOS_H__

#include <stdarg.h>
#include "windef.h"
#include "winbase.h"
#include "lm.h"
#include "nb30.h"

/* This file describes the interface WINE's NetBIOS implementation uses to
 * interact with a transport implementation (where a transport might be
 * NetBIOS-over-TCP/IP (aka NetBT, NBT), NetBIOS-over-IPX, etc.)
 */

/**
 * Public functions
 */

void NetBIOSInit(void);
void NetBIOSShutdown(void);

struct _NetBIOSTransport;

/* A transport should register itself during its init function (see below) with
 * a unique id (the transport_id of ACTION_HEADER, for example) and an
 * implementation.  Returns TRUE on success, and FALSE on failure.
 */
BOOL NetBIOSRegisterTransport(ULONG id, struct _NetBIOSTransport *transport);

/* Registers an adapter with the given transport and ifIndex with NetBIOS.
 * ifIndex is an interface index usable by the IpHlpApi.  ifIndex is not
 * required to be unique, but is required so that NetWkstaTransportEnum can use
 * GetIfEntry to get the name and hardware address of the adapter.
 * Returns TRUE on success, FALSE on failure.
 * FIXME: need functions for retrieving the name and hardware index, rather
 * than assuming a correlation with IpHlpApi.
 */
BOOL NetBIOSRegisterAdapter(ULONG transport, DWORD ifIndex, void *adapter);

/* During enumeration, all adapters from your transport are disabled
 * internally.  If an adapter is still valid, reenable it with this function.
 * Adapters you don't enable will have their transport's NetBIOSCleanupAdapter
 * function (see below) called on them, and will be removed from the table.
 * (This is to deal with lack of plug-and-play--sorry.)
 */
void NetBIOSEnableAdapter(UCHAR lana);

/* Gets a quick count of the number of NetBIOS adapters.  Not guaranteed not
 * to change from one call to the next, depending on what's been enumerated
 * lately.  See also NetBIOSEnumAdapters.
 */
UCHAR NetBIOSNumAdapters(void);

typedef struct _NetBIOSAdapterImpl {
    UCHAR lana;
    DWORD ifIndex;
    void *data;
} NetBIOSAdapterImpl;

typedef BOOL (*NetBIOSEnumAdaptersCallback)(UCHAR totalLANAs, UCHAR lanaIndex,
 ULONG transport, const NetBIOSAdapterImpl *data, void *closure);

/* Enumerates all NetBIOS adapters for the transport transport, or for all
 * transports if transport is ALL_TRANSPORTS.  Your callback will be called
 * once for every enumerated adapter, with a count of how many adapters have
 * been enumerated, a 0-based index relative to that count, the adapter's
 * transport, and its ifIndex.
 * Your callback should return FALSE if it no longer wishes to be called.
 */
void NetBIOSEnumAdapters(ULONG transport, NetBIOSEnumAdaptersCallback cb,
 void *closure);

/* Hangs up the session identified in the NCB; the NCB need not be a NCBHANGUP.
 * Will result in the transport's hangup function being called, so release any
 * locks you own before calling to avoid deadlock.
 * This function is intended for use by a transport, if the session is closed
 * by some error in the transport layer.
 */
void NetBIOSHangupSession(PNCB ncb);

/**
 * Functions a transport implementation must implement
 */

/* This function is called to ask a transport implementation to enumerate any
 * LANAs into the NetBIOS adapter table by:
 * - calling NetBIOSRegisterAdapter for any new adapters
 * - calling NetBIOSEnableAdapter for any existing adapters
 * NetBIOSEnumAdapters (see) may be of use to determine which adapters already
 * exist.
 * A transport can assume no other thread is modifying the NetBIOS adapter
 * table during the lifetime of its NetBIOSEnum function (and, therefore, that
 * this function won't be called reentrantly).
 */
typedef UCHAR (*NetBIOSEnum)(void);

/* A cleanup function for a transport.  This is the last function called on a
 * transport.
 */
typedef void (*NetBIOSCleanup)(void);

/* Adapter functions */

/* Functions with direct mappings to the Netbios interface.  These functions
 * are expected to be synchronous, although the first four bytes of the
 * reserved member of the ncb are a cancel flag.  A long-running function
 * should check whether this is not FALSE from time to time (see the
 * NCB_CANCELLED macro), and return NRC_CMDCAN if it's been cancelled.  (The
 * remainder of the NCB's reserved field is, well, reserved.)
 */

/* Used to see whether the pointer to an NCB has been cancelled.  The NetBIOS
 * interface designates certain functions as non-cancellable functions, but I
 * use this flag for all NCBs.  Support it if you can.
 * FIXME: this isn't enough, need to support an EVENT or some such, because
 * some calls (recv) will block indefinitely, so a reset, shutdown, etc. will
 * never occur.
 */
135
#define NCB_CANCELLED(pncb) *(PBOOL)((pncb)->ncb_reserve)
136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183

typedef UCHAR (*NetBIOSAstat)(void *adapter, PNCB ncb);
typedef UCHAR (*NetBIOSFindName)(void *adapter, PNCB ncb);

/* Functions to support the session service */

/* Implement to support the NCBCALL command.  If you need data stored for the
 * session, return it in *session.  You can clean it up in your NetBIOSHangup
 * function (see).
 */
typedef UCHAR (*NetBIOSCall)(void *adapter, PNCB ncb, void **session);
typedef UCHAR (*NetBIOSSend)(void *adapter, void *session, PNCB ncb);
typedef UCHAR (*NetBIOSRecv)(void *adapter, void *session, PNCB ncb);
typedef UCHAR (*NetBIOSHangup)(void *adapter, void *session);

/* The last function called on an adapter; it is not called reentrantly, and
 * no new calls will be made on the adapter once this has been entered.  Clean
 * up any resources allocated for the adapter here.
 */
typedef void (*NetBIOSCleanupAdapter)(void *adapter);

typedef struct _NetBIOSTransport
{
    NetBIOSEnum           enumerate;
    NetBIOSAstat          astat;
    NetBIOSFindName       findName;
    NetBIOSCall           call;
    NetBIOSSend           send;
    NetBIOSRecv           recv;
    NetBIOSHangup         hangup;
    NetBIOSCleanupAdapter cleanupAdapter;
    NetBIOSCleanup        cleanup;
} NetBIOSTransport;

/* Transport-specific functions.  When adding a transport, add a call to its
 * init function in netapi32's DllMain.  The transport can do any global
 * initialization it needs here.  It should call NetBIOSRegisterTransport to
 * register itself with NetBIOS.
 */

/* NetBIOS-over-TCP/IP (NetBT) functions */

/* Not defined by MS, so make my own private define: */
#define TRANSPORT_NBT "MNBT"

void NetBTInit(void);

#endif /* ndef __WINE_NETBIOS_H__ */