Class: Mail::Sympa

Inherits:
Object
  • Object
show all
Defined in:
lib/mail/sympa.rb

Overview

The Sympa module encapsulates the various Sympa server SOAP methods

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =

The version of the mail-sympa library.

'1.1.0'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(endpoint, namespace = 'urn:sympasoap') ⇒ Sympa

Creates and returns a new Mail::Sympa object based on the endpoint (the endpoint URL) and a namespace which defaults to ‘urn:sympasoap’.

Example:

sympa = Mail::Sympa.new('http://your.sympa.home/sympasoap')



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
 
# File 'lib/mail/sympa.rb', line 30

def initialize(endpoint, namespace = 'urn:sympasoap')
  @endpoint  = endpoint.to_s # Allow for URI objects
  @namespace = namespace

  @soap = SOAP::RPC::Driver.new(endpoint, namespace)

  @email    = nil
  @password = nil
  @cookie   = nil

  @soap.add_method('login', 'email', 'password')

  @soap.add_method(
    'authenticateAndRun',
    'email',
    'cookie',
    'service',
    'parameters'
  )

  @soap.add_method(
    'authenticateRemoteAppAndRun',
    'appname',
    'apppassword',
    'vars',
    'service',
    'parameters'
  )
end

Instance Attribute Details

The session cookie returned by the login method.



15
16
17
 
# File 'lib/mail/sympa.rb', line 15

def cookie
  @cookie
end

#endpoint ⇒ Object (readonly) Also known as: url

The endpoint URL of the SOAP service.



18
19
20
 
# File 'lib/mail/sympa.rb', line 18

def endpoint
  @endpoint
end

#namespace ⇒ Object (readonly)

The URN namespace. The default is ‘urn:sympasoap’.



21
22
23
 
# File 'lib/mail/sympa.rb', line 21

def namespace
  @namespace
end

Instance Method Details

#add(email, list_name, name, quiet = true) ⇒ Object

Adds the given email to list_name using name (gecos). If quiet is set to true (the default) then no email notification is sent. – TODO: Determine why this method does not return a boolean.

Raises:



200
201
202
203
 
# File 'lib/mail/sympa.rb', line 200

def add(email, list_name, name, quiet=true)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'add', [list_name, email, name, quiet])
end

#am_i?(user, list_name, function = 'editor') ⇒ Boolean Also known as: amI

Returns a boolean indicating whether or not user has function on list_name. The two possible values for function are ‘editor’ and ‘owner’.

Returns:

  • (Boolean)

Raises:



183
184
185
186
187
188
189
190
191
 
# File 'lib/mail/sympa.rb', line 183

def am_i?(user, list_name, function = 'editor')
  raise Error, 'must login first' unless @cookie

  unless ['editor', 'owner'].include?(function)
    raise Error, 'invalid function name "#{editor}"'
  end

  @soap.authenticateAndRun(@email, @cookie, 'amI', [list_name, function, user])
end

#authenticate_remote_app_and_run(app_name, app_password, variables, service, parameters) ⇒ Object Also known as: authenticateRemoteAppAndRun

Run command in trusted context.



253
254
255
 
# File 'lib/mail/sympa.rb', line 253

def authenticate_remote_app_and_run(app_name, app_password, variables, service, parameters)
  @soap.authenticateRemoteAppAndRun( app_name, app_password, variables, service, parameters ) 
end

#close_list(list_name) ⇒ Object Also known as: closeList

Closes list list_name. Returns boolean.

Raises:



245
246
247
248
 
# File 'lib/mail/sympa.rb', line 245

def close_list(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'closeList', [list_name])
end

#complex_lists(topic = '', sub_topic = '') ⇒ Object Also known as: complexLists

Returns an array of available mailing lists in complex object format, i.e. these are SOAP::Mapping objects that you can call methods on.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.complex_lists.each{ |list|
  puts list.subject
  puts list.homepage
}

Raises:



106
107
108
109
110
 
# File 'lib/mail/sympa.rb', line 106

def complex_lists(topic='', sub_topic='')
  raise Error, 'must login first' unless @cookie
  args = [topic, sub_topic]
  @soap.authenticateAndRun(@email, @cookie, 'complexLists', args)
end

#complex_which(user, app_name, app_passwd) ⇒ Object Also known as: complexWhich

Same as the Sympa#which method, but returns an array of SOAP::Mapping objects that you can call methods on.

Raises:



172
173
174
175
 
# File 'lib/mail/sympa.rb', line 172

def complex_which(user, app_name, app_passwd)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'complexWhich', [''])
end

#create_list(list_name, subject, template = 'discussion_list', description = ' ', topics = ' ') ⇒ Object Also known as: createList

Creates list list_name with subject subject. Returns boolean.

Raises:



236
237
238
239
 
# File 'lib/mail/sympa.rb', line 236

def create_list(list_name, subject, template='discussion_list', description=' ', topics=' ')
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'createList', [list_name, subject, template, description, topics])
end

#del(email, list_name, quiet = true) ⇒ Object Also known as: delete

Deletes the given email from list_name. If quiet is set to true (the default) then no email notification is sent. – TODO: Determine why this method does not return a boolean.

Raises:



210
211
212
213
 
# File 'lib/mail/sympa.rb', line 210

def del(email, list_name, quiet=true)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'del', [list_name, email, quiet])
end

#info(list_name) ⇒ Object

Returns a description about the given list_name. This is a SOAP::Mapping object.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

info = sympa.info(list)

puts info.subject
puts info.homepage
puts info.isOwner

Raises:



128
129
130
131
 
# File 'lib/mail/sympa.rb', line 128

def info(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'info', [list_name])
end

#lists(topic = '', sub_topic = '') ⇒ Object

Returns an array of available mailing lists based on topic and sub_topic. If sub_topic is nil then all sub-topics are returned. If topic is nil then all lists are returned.

The returned lists contains an array of strings. If you prefer objects with methods corresponding to keys, see complex_lists instead.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.lists.each{ |list| puts list }

Raises:



88
89
90
91
 
# File 'lib/mail/sympa.rb', line 88

def lists(topic='', sub_topic='')
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'lists', [topic, sub_topic])
end

#login(email, password) ⇒ Object

Authenticate with the Sympa server. This method must be called before any other methods can be used successfully.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)



68
69
70
71
72
 
# File 'lib/mail/sympa.rb', line 68

def (email, password)
  @email    = email
  @password = password
  @cookie   = @soap.(email, password)
end

#review(list_name) ⇒ Object

Returns an array of members that belong to the given list_name.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

sympa.review(list)

Raises:



142
143
144
145
 
# File 'lib/mail/sympa.rb', line 142

def review(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'review', [list_name])
end

#signoff(list_name) ⇒ Object Also known as: unsubscribe

Removes the currently logged in user from list_name.

Raises:



225
226
227
228
 
# File 'lib/mail/sympa.rb', line 225

def signoff(list_name)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'signoff', [list_name, @email])
end

#subscribe(list_name, name = @email) ⇒ Object

Subscribes the currently logged in user to list_name. By default the name (gecos) will be the email address.

Raises:



218
219
220
221
 
# File 'lib/mail/sympa.rb', line 218

def subscribe(list_name, name = @email)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateAndRun(@email, @cookie, 'subscribe', [list_name, name])
end

#which(user, app_name, app_passwd) ⇒ Object

Returns an array of lists that the user is subscribed to. The user should include the proxy variable setup in the trusted_applications.conf file.

The app_name is whatever is set in your trusted_applications.conf file. The app_password for that app must also be provided.

Example:

sympa = Mail::Sympa.new(url)
sympa.(email, password)

# If vars contains USER_EMAIL
sympa.which('[email protected]', 'my_app', 'my_password')

An alternative is to use complex_lists + review, though it’s slower.

Raises:



164
165
166
167
 
# File 'lib/mail/sympa.rb', line 164

def which(user, app_name, app_passwd)
  raise Error, 'must login first' unless @cookie
  @soap.authenticateRemoteAppAndRun(app_name, app_passwd, user, 'which', [''])
end