Login to Salesforce.com and starts a client session.

    Unlike other toolkits, token is a separate parameter, because
    Salesforce doesn't explicitly tell you to append it when it gives
    you a login error.  Folks that are new to the API may not know this.

    'username' : Username
    'password' : Password
    'token' : Token

    return LoginResult

def login(self, username, password, token):
    '''
    Login to Salesforce.com and starts a client session.

    Unlike other toolkits, token is a separate parameter, because
    Salesforce doesn't explicitly tell you to append it when it gives
    you a login error.  Folks that are new to the API may not know this.

    'username' : Username
    'password' : Password
    'token' : Token

    return LoginResult
    '''
    self._setHeaders('login')
    result = self._sforce.service.login(username, password + token)

    # set session header
    header = self.generateHeader('SessionHeader')
    header.sessionId = result['sessionId']
    self.setSessionHeader(header)
    self._sessionId = result['sessionId']
    self._userId = result['userId']
    self._metadataServerUrl = result['metadataServerUrl']

    # change URL to point from test.salesforce.com to something like cs2-api.salesforce.com
    self._setEndpoint(result['serverUrl'])

    # na0.salesforce.com (a.k.a. ssl.salesforce.com) requires ISO-8859-1 instead of UTF-8
    if 'ssl.salesforce.com' in result['serverUrl'] or 'na0.salesforce.com' in result['serverUrl']:
      # currently, UTF-8 is hard-coded in Suds, can't implement this yet
      pass

    return result