opennet.h

.net 方面的开发说明资料。

	DLL_API bool DLL_CALLCONV EpLoadProperties(PROPERTYGROUP_HANDLE group, const char *properties);

	// ----------------------------------------------------------
	// Purpose: Returns the type of a property group.
	// Usage  : None
	// ----------------------------------------------------------
	
	DLL_API bool DLL_CALLCONV EpPropGetType(PROPERTYGROUP_HANDLE group, char *type);
	
	// ----------------------------------------------------------
	// Purpose: Returns true if the property group contains the
	//          given property key, false otherwise. Property keys
	//          are case insensitive.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpPropKeyExists(PROPERTYGROUP_HANDLE group, const char *s);

	// ----------------------------------------------------------
	// Purpose: Returns the value of the given key in a property
	//          group. Returns true if the function was
	//          successfull, false otherwise.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpPropGetValue(PROPERTYGROUP_HANDLE group, const char *key, char *value);

	// ----------------------------------------------------------
	// Purpose: Returns the value of the given key in a property
	//          group, converted to a boolean. Returns true if
	//          the function was successfull, false otherwise.
	//          The property is true if the value is the string
	//          "true" or a numeric value other than 0.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpPropGetValueAsBool(PROPERTYGROUP_HANDLE group, const char *key, bool *value);

	// ----------------------------------------------------------
	// Purpose: Returns the value of the given key in a property
	//          group, converted to an integer. Returns true if
	//          the function was successfull, false otherwise.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpPropGetValueAsInt(PROPERTYGROUP_HANDLE group, const char *key, int *value);

	// ----------------------------------------------------------
	// Purpose: Returns the value of the given key in a property
	//          group, converted to an unsigned long. Returns
	//          true if the function was successfull, false
	//          otherwise.
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpDestroyPropertyGroup(PROPERTYGROUP_HANDLE group);

	// ##########################################################
	// TRANSPORT FUNCTIONS
	// ##########################################################
	// ----------------------------------------------------------
	// Purpose: Creates a new transport
	// Usage  : Use this function to start a communication
	//          session. The transport_type parameter specifies the
	//          type of transport to be created (rs232, tcpip, etc).
	// Notes: : None
	// ----------------------------------------------------------

	DLL_API TRANSPORT_HANDLE DLL_CALLCONV EpCreateTransport(const char *properties, CallbackProc callback, bool enable_debug_events = false, void *data = NULL);

	// ----------------------------------------------------------
	// Purpose: Destroys a previously created transport
	// Usage  : None
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpDestroyTransport(TRANSPORT_HANDLE transport);

	// ----------------------------------------------------------
	// Purpose: Enables or disables the postage of debug events
	//          for a specific transports. These events include
	//          SYSTEM_DATA_IN and SYSTEM_DATA_OUT. More events
	//          might be included in the future
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpEnableDebugEvents(TRANSPORT_HANDLE transport, bool enable);

	// ----------------------------------------------------------
	// Purpose: Gets a transport option
	// Usage  : None
	// Notes  : If value is NULL and size is not NULL, size will
	//          contain the needed size to contain the option.
	// ----------------------------------------------------------
	
	DLL_API bool DLL_CALLCONV EpGetOption(TRANSPORT_HANDLE transport, int option, void *value, int *size);

	// ----------------------------------------------------------
	// Purpose: Sets a transport option
	// Usage  : None
	// Notes  : None
	// ----------------------------------------------------------
	
	DLL_API bool DLL_CALLCONV EpSetOption(TRANSPORT_HANDLE transport, int option, void *value);

	// ##########################################################
	// PROTOCOL FUNCTIONS
	// ##########################################################
	// ----------------------------------------------------------
	// Purpose: Wrapper for EpRegisterComponent that automatically
	//          registers a protocol.
	// Usage  : None
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpRegisterProtocol(CLSID id, Protocol *protocol);

	// ----------------------------------------------------------
	// Purpose: Adds a protocol on a transport
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpAddProtocol(TRANSPORT_HANDLE transport, GUID protocol_id);

	// ----------------------------------------------------------
	// Purpose: Resets a protocol
	// Usage  : None
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpResetProtocol(TRANSPORT_HANDLE handle, GUID protocol);

	// ----------------------------------------------------------
	// Purpose: Retrieves a registered protocol from a GUID.
	// Usage  : None
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API Protocol *DLL_CALLCONV EpProtocolHandle(CLSID id);

	// ----------------------------------------------------------
	// Purpose: Connects to an external source
	// Usage  : Use this function to connect a transport to
	//          an external host, such as a modem or an internet
	//          service.
	// Notes  : Each transport-type has its own way, non compatible
	//          way of plugging into external servers. However,
	//          OpenNet tries to unify them by sending an
	//          internal event SYSTEM_CONNECTED when a connection
	//          was successfulor SYSTEM_CONNECTION_FAILED when the
	//          connection couldn't be made.
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpConnect(TRANSPORT_HANDLE transport, const char *host, int port, int timeout);

	// ----------------------------------------------------------
	// Purpose: Disconnects from an external source
	// Usage  : Use this function to disconnect a transport from an
	//          external host, such as a modem or an internet
	//          service.
	// Notes  : Each transport-type has its own, non compatible
	//          way of plugging to external sources. However,
	//          OpenNet tries to unify them by sending an
	//          internal event SYSTEM_DISCONNECTED when a connection
	//          was successfully aborted. If a connection could not me 
	//          aborted SYSTEM_DISCONNECTION_FAILED is sent. Any
	//          internal events for the specific transport-type are
	//          also sent.
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpDisconnect(TRANSPORT_HANDLE transport);
		
	// ----------------------------------------------------------
	// Purpose: Sends an action to a transport
	// Usage  : Whenever you want to send some data to a transport
	//          you have to create an event for it. The transport
	//          accepts the event, transforms it to data for
	//          the target device via a protocol router, and then
	//          sends the data to the target device. When data 
	//          is received, the data is once again lead through
	//          the protocol and transformed to an EpEvent. Then
	//          the event is sent to the Grid's callback function.
	// Notes  : The event data is sent to the protocol, transformed,
	//          and immediately sent to the transport, When this function
	//          returns, you can immediately clean up the event.
	// 
	//          When a transport is attached to a protocol, you *MUST*
	//          call CompleteEvent to finish the event off.
	//          Failing to do so will cause OpenNet to ignore
	//          the event completely.
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpSendAction(TRANSPORT_HANDLE transport, EpAction *action);

	// ----------------------------------------------------------
	// Purpose: Sends transformed data from the protocol to the
	//          transport
	// Usage  : This function initiates the actual data transfer
	//          in the transport. You should only use this
	//          function in a protocol implementation.
	// Notes  : The sent data is copied inside the transport, to
	//          ensure reliable communication. When this function
	//          returns, you can immediately delete the data.
	// Notes  : If the protocol member in the EpEvent is nonzero,
	//          then the data in the data member is send through
	//          a assigned protocol object. The protocol then calls
	//          EpCompleteEvent to send the actual (translated) data.
	//          If the protocol member is zero, OpenNet sees the
	//          data in the data member as raw data and sends
	//          immediately.
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpCompleteAction(TRANSPORT_HANDLE transport, unsigned char *data, int size);

	// ----------------------------------------------------------
	// Purpose: Dispatches an EpEvent to the grid callback
	// Usage  : This function is probably only of use in
	//          protocols. It takes a EpEvent, and sends it
	//          to a grid's callback function. The user can
	//          then do something according to the EpEvent he
	//          received.
	// Notes  : The event data is copied and stored in a queue.
	//          You may immediately clean up the event after
	//          this function returns.
	// Notes  : When the user handled the dispatched message,
	//          he must call EpHandledEvent to notify OpenNet that
	//          the event data can be destroyed.
	// Notes  : If the size member in the event is larger than 0,
	//          the data member is ignored.
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpDispatchEvent(TRANSPORT_HANDLE transport, EpEvent *event);

	// ----------------------------------------------------------
	// Purpose: Sends raw data to a transport
	// Usage  : This is a convenient wrapper to directly
	//          pass raw data to a transport, without creating a
	//          EpEvent. Normally you would create a EpEvent
	//          with the protocol member set to 0.
	// Notes  : Because there is no protocol attached to raw
	//          data, you may decide what kind of event you
	//          want to see in return. If the reply_protocol
	//          parameter is 0, the reply event will be a
	//          system event. Otherwise it will be an event
	//          of the protocol assigned to the transport on creation.
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpSendRawData(TRANSPORT_HANDLE transport, unsigned char *data, int size, GUID reply_protocol, int reply_msg, int timeout);

	// ----------------------------------------------------------
	// Purpose: Notifies OpenNet that a reply arrived for an event.
	// Usage  : When an event is sent with a positive value time-
    //          out, OpenNet will send an SYSTEM_TIMEOUT event
	//          when the given time has elapsed. When this function
	//          is called, the timeout event is supressed.
	// Notes  : When there were sent multiple events with the same
	//          type, EpHandledEvent removes them in the order they
	//          were sent, regardless of differences in the time-out
	//          values.
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpCancelTimeout(TRANSPORT_HANDLE transport, GUID protocol, int msg);

	// ----------------------------------------------------------
	// Purpose: Cancels all scheduled timeouts for a specific protocol
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpCancelProtocolTimeouts(TRANSPORT_HANDLE transport, GUID protocol);

	// ----------------------------------------------------------
	// Purpose: Cancels all timeouts for a transport
	// ----------------------------------------------------------

	DLL_API bool DLL_CALLCONV EpCancelAllTimeouts(TRANSPORT_HANDLE transport);

	// ----------------------------------------------------------
	// Purpose: Retrieves some extra reference data from an event
	// Usage  : A transport might store some extra reference data
	//          when it posts an event. For example an UDP
	//          transport stores the ip address of the user that
	//          sent the packet.
	// Notes  : None
	// ----------------------------------------------------------

	DLL_API void *DLL_CALLCONV EpGetEventRefData(TRANSPORT_HANDLE transport, int reference);

	// ----------------------------------------------------------
	// Purpose: Sends unhandled data from the protocol to the
	//          system.
	// Usage  : Whenever a protocol finds data it can't handle,
	//          it can send it to the previous protocol in the
	//          inheritance chain and ultimately to a built
	//          in protocol for a particular transport (the
	//          'system' protocol)
	// ----------------------------------------------------------

	DLL_API void DLL_CALLCONV EpInheritedRecv(TRANSPORT_HANDLE transport, unsigned char *data, int size);

	// ----------------------------------------------------------
	// Purpose: Retrieves the name string of a protocol
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API int DLL_CALLCONV EpGetProtocolName(TRANSPORT_HANDLE transport, GUID protocol, char *name, int size);

	// ----------------------------------------------------------
	// Purpose: Retrieves the name string of a message handled
	//          by a certain protocol
	// Usage  : None
	// ----------------------------------------------------------

	DLL_API int DLL_CALLCONV EpGetProtocolMsgName(TRANSPORT_HANDLE transport, GUID protocol, int msg, char *name, int size);
};

#endif