metasploit-framework/lib/rex/socket/comm.rb

121 lines
2.7 KiB
Ruby
Raw Normal View History

# -*- coding: binary -*-
require 'rex/socket'
module Rex
module Socket
###
#
# This mixin provides the basic interface that a derived class must implement
# in order to be a compatible comm class. The base comm class also supports
# registering event handlers that can be notified when sockets are being
# created and have been created. This allows code to extend sockets on
# creation from the single point that they are created.
#
###
module Comm
###
2013-03-08 00:16:57 +00:00
#
# This mixin provides stubs for event notification handlers that can be
# registered with a Comm factory to be called when various events occur,
# such as socket instantiation.
#
###
module Events
#
# This callback is notified when a socket is being created and is passed
# the parameters that will be used to create it.
#
def on_before_socket_create(comm, param)
end
#
# This callback is notified when a new socket is created and the
# parameters that were used to create it. This provides the callback
# with a chance to extend or otherwise modify the socket before it's
# passed on to the actual requestor.
#
def on_socket_created(comm, sock, param)
end
end
#
# Creates a compatible socket based on the supplied uniform parameters.
#
def self.create(param)
raise NotImplementedError
end
#
# Indicates whether or not this comm can be chained with other chainable
# comms. This is particularly important for things like Proxy Comms that
# can be proxied through one another. The semantics of this are currently
# undefined and will probably need some more thought.
#
def chainable?
false
end
#
# Registers an event handler that implements the Rex::Socket::Comm::Event
# interface in at least some fashion. Event handlers are notified when
# sockets are created through the Comm instance that they register against.
#
def register_event_handler(handler)
if (handlers == nil)
self.handlers = []
end
self.handlers << handler
end
#
# Deregisters a previously registered event handler.
#
def deregister_event_handler(handler)
if (handlers)
handlers.delete(handler)
end
end
#
# Enumerates each registered event handler so that they can be notified of
# an event.
#
def each_event_handler(&block)
if (handlers)
handlers.each(&block)
end
end
#
# Notifies handlers of the before socket create event.
#
def notify_before_socket_create(comm, param)
each_event_handler() { |handler|
handler.on_before_socket_create(comm, param)
}
end
#
# Notifies handlers of the socket created event.
#
def notify_socket_created(comm, sock, param)
each_event_handler() { |handler|
handler.on_socket_created(comm, sock, param)
}
end
protected
attr_accessor :handlers # :nodoc:
attr_accessor :handlers_rwlock # :nodoc:
end
end
end